@uncefact/untp-utils 0.1.0 → 0.3.0

package/build/validation/describe-jsonld-failure.js

@@ -0,0 +1,171 @@
+import { JsonLdInvalidShapeError } from './errors.js';
+import { ResolverError, ResolverInvalidJsonError } from '../resolvers/errors.js';
+import { UrlValidationError } from '../node/errors.js';
+const GENERIC_DOCUMENT_DETAIL = 'the document could not be expanded as valid JSON-LD';
+const GENERIC_REMOTE_CONTEXT_DETAIL = 'a remote @context response could not be used as a JSON-LD context';
+const REMOTE_CONTEXT_CHAIN_DETAIL = 'the remote @context chain could not be resolved: too many remote contexts, or a remote context refers back to itself';
+const GENERIC_REMOTE_CONTEXT_LOAD_DETAIL = 'a remote @context document could not be loaded';
+const FLAT_URL_POLICY_DETAIL = "a remote @context URL was rejected by this service's URL policy or could not be resolved";
+/** Event `details` fields safe to echo: identifiers from the caller's own document or a public context, never free-form values that can carry credential content. */
+/** The only jsonld.js event and syntax-error detail fields ever echoed to a caller; everything else may carry document content. */
+export const SAFE_EVENT_FIELDS = ['property', 'expandedProperty', 'id', 'type', 'term', 'language', 'vocab'];
+const MAX_FIELD_LENGTH = 200;
+function isJsonLdProcessorError(value) {
+    return value instanceof Error && value.name.startsWith('jsonld.');
+}
+/** The allowlisted string fields present on a details object, truncated. */
+function safeFields(details) {
+    const fields = {};
+    for (const field of SAFE_EVENT_FIELDS) {
+        const value = details?.[field];
+        if (typeof value === 'string' && value !== '')
+            fields[field] = value.slice(0, MAX_FIELD_LENGTH);
+    }
+    return Object.keys(fields).length > 0 ? fields : undefined;
+}
+/** Formats a safe-mode event: its fixed library message plus allowlisted string fields. */
+function describeSafeModeEvent(event) {
+    const parts = [];
+    if (typeof event.message === 'string' && event.message !== '') {
+        parts.push(event.message);
+    }
+    for (const [field, value] of Object.entries(safeFields(event.details) ?? {})) {
+        parts.push(`(${field}: "${value}")`);
+    }
+    return parts.length > 0 ? parts.join(' ') : GENERIC_DOCUMENT_DETAIL;
+}
+const stringOr = (value) => typeof value === 'string' && value !== '' ? value : undefined;
+function* causeChain(error) {
+    const seen = new Set();
+    let current = error;
+    while (current !== undefined && !seen.has(current)) {
+        seen.add(current);
+        yield current;
+        current = current instanceof Error ? current.cause : undefined;
+    }
+}
+/**
+ * Classifies a {@link JsonLdValidationError} by walking its cause chain
+ * (native `.cause` hops; the chain is rehydrated by `validateJsonLd`, see
+ * issue #773).
+ *
+ * The passes run in a load-bearing order. The rehydrated chain nests the
+ * guarded loader's error BENEATH jsonld.js's own wrapper
+ * (`JsonLdExpansionFailedError` -> `jsonld.InvalidUrl` -> the loader's
+ * `UrlValidationError`), and the wrapper's message contains the URL, so no
+ * jsonld.js message may become `detail` until the typed-loader pass has
+ * exhausted the whole chain; matching the wrapper's message first would
+ * reopen the per-hostname reconnaissance oracle the flat message exists to
+ * close. The URL scan that runs before the typed-loader pass reads only the
+ * wrapper's `details.url`, which is the caller's own document's URL.
+ *
+ * `UrlValidationError` deliberately collapses to one flat message: its
+ * subclasses distinguish "does not resolve" from "resolves to a private
+ * address" from "scheme not allowed", and echoing that distinction would
+ * hand an authenticated caller a network-reconnaissance oracle over
+ * attacker-chosen `@context` URLs. The full typed diagnostic stays on the
+ * cause chain for the server-side log. `ResolverError` diagnostics fire
+ * only after the URL passed the public-address check, so their detail
+ * (HTTP status, timeout, size bound) is returned as-is.
+ *
+ * Known limitation, accepted: a malformed term definition inside a
+ * successfully fetched remote context surfaces as a `jsonld.SyntaxError`
+ * indistinguishable from the same defect in an inline context, and is
+ * classified as a document failure.
+ */
+export function describeJsonLdFailure(error) {
+    // Our own pre-expansion diagnostic: safe, typed, and more precise than
+    // the generic fallback (expansion never ran).
+    if (error instanceof JsonLdInvalidShapeError) {
+        return { kind: 'document', detail: error.message, code: 'invalid document shape' };
+    }
+    // The failing @context URL, when jsonld.js recorded one on its wrapper: a
+    // URL from the caller's document, or one a remote context it named refers
+    // to. Either way it is a public URL the caller caused to be requested,
+    // never the address it resolved to.
+    let url;
+    for (const node of causeChain(error)) {
+        if (isJsonLdProcessorError(node) && node.name === 'jsonld.InvalidUrl') {
+            url = stringOr(node.details?.url);
+            break;
+        }
+    }
+    // Pass 1: the guarded loader's typed failures, anywhere on the chain.
+    for (const node of causeChain(error)) {
+        if (node instanceof UrlValidationError) {
+            return { kind: 'context-fetch', detail: FLAT_URL_POLICY_DETAIL, ...(url && { url }) };
+        }
+        if (node instanceof ResolverInvalidJsonError) {
+            // Thrown only after a response body was read and failed to parse: the
+            // artefact, not the delivery, is at fault.
+            return { kind: 'context-invalid', detail: GENERIC_REMOTE_CONTEXT_DETAIL, code: node.code, ...(url && { url }) };
+        }
+        if (node instanceof ResolverError) {
+            return {
+                kind: 'context-fetch',
+                detail: `could not fetch a remote @context: ${node.message}`,
+                code: node.code,
+                ...(url && { url }),
+            };
+        }
+    }
+    // Pass 2: recognised jsonld.js processor shapes (name plus details.code
+    // matched exactly; the name prefix alone only locates the processor error,
+    // it does not make its message caller-safe).
+    for (const node of causeChain(error)) {
+        if (!isJsonLdProcessorError(node))
+            continue;
+        const code = stringOr(node.details?.code);
+        if (node.name === 'jsonld.InvalidUrl' && code === 'invalid remote context') {
+            // Fetched successfully but not usable as a context: the artefact, not
+            // the document, is at fault.
+            return { kind: 'context-invalid', detail: GENERIC_REMOTE_CONTEXT_DETAIL, code, ...(url && { url }) };
+        }
+        if (node.name === 'jsonld.InvalidUrl' && code === 'loading remote context failed') {
+            // Rejected by an untyped loader path, so the typed pass found nothing:
+            // the context could not be loaded, and the wrapper's message (which
+            // names the URL) is not echoed.
+            return { kind: 'context-fetch', detail: GENERIC_REMOTE_CONTEXT_LOAD_DETAIL, code, ...(url && { url }) };
+        }
+        if (node.name === 'jsonld.ContextUrlError') {
+            // jsonld.js throws this only while resolving a chain of remote contexts
+            // (too many, or one that refers back to itself); a cycle between local
+            // term definitions is jsonld.CyclicalContext and stays a document fault.
+            return { kind: 'context-fetch', detail: REMOTE_CONTEXT_CHAIN_DETAIL, ...(code && { code }), ...(url && { url }) };
+        }
+        if (node.name === 'jsonld.SyntaxError' && code === 'invalid scoped context') {
+            // A term-scoped remote context whose body was unusable: jsonld.js
+            // discards the original error, so only the term survives.
+            const fields = safeFields(node.details);
+            return { kind: 'context-invalid', detail: GENERIC_REMOTE_CONTEXT_DETAIL, code, ...(fields && { fields }) };
+        }
+        if (node.name === 'jsonld.ValidationError' && node.details?.event !== undefined) {
+            const event = node.details.event;
+            const fields = safeFields(event.details);
+            return {
+                kind: 'document',
+                detail: describeSafeModeEvent(event),
+                source: 'safe-mode-event',
+                ...(stringOr(event.code) && { code: stringOr(event.code) }),
+                ...(fields && { fields }),
+            };
+        }
+        if (node.name === 'jsonld.SyntaxError') {
+            // jsonld.js interpolates caller values into some syntax messages
+            // (jsonld@8.3.3 lib/context.js: an @index value, a term, a type), so
+            // the message is never echoed; the recognised code and the allowlisted
+            // identifiers are the whole diagnostic.
+            const fields = safeFields(node.details);
+            return {
+                kind: 'document',
+                detail: code ? `Invalid JSON-LD syntax; ${code}.` : GENERIC_DOCUMENT_DETAIL,
+                source: 'syntax-error',
+                ...(code && { code }),
+                ...(fields && { fields }),
+            };
+        }
+        return { kind: 'document', detail: GENERIC_DOCUMENT_DETAIL };
+    }
+    return { kind: 'document', detail: GENERIC_DOCUMENT_DETAIL };
+}
+//# sourceMappingURL=describe-jsonld-failure.js.map

package/build/validation/describe-jsonld-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-jsonld-failure.js","sourceRoot":"","sources":["../../src/validation/describe-jsonld-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAyB,MAAM,aAAa,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AA8DvD,MAAM,uBAAuB,GAAG,qDAAqD,CAAC;AACtF,MAAM,6BAA6B,GAAG,mEAAmE,CAAC;AAC1G,MAAM,2BAA2B,GAC/B,sHAAsH,CAAC;AACzH,MAAM,kCAAkC,GAAG,gDAAgD,CAAC;AAC5F,MAAM,sBAAsB,GAC1B,0FAA0F,CAAC;AAE7F,qKAAqK;AACrK,mIAAmI;AACnI,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AACtH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAQ7B,SAAS,sBAAsB,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACpE,CAAC;AAED,4EAA4E;AAC5E,SAAS,UAAU,CAAC,OAA4C;IAC9D,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,iBAAiB,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,2FAA2F;AAC3F,SAAS,qBAAqB,CAAC,KAA+D;IAC5F,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QAC9D,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7E,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB,CAAC;AACtE,CAAC;AAED,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAsB,EAAE,CACtD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAEhE,QAAQ,CAAC,CAAC,UAAU,CAAC,KAAc;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAChC,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,OAAO,CAAC;QACd,OAAO,GAAG,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,uEAAuE;IACvE,8CAA8C;IAC9C,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;IACrF,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,uEAAuE;IACvE,oCAAoC;IACpC,IAAI,GAAuB,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;YACtE,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAClC,MAAM;QACR,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,IAAI,YAAY,kBAAkB,EAAE,CAAC;YACvC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACxF,CAAC;QACD,IAAI,IAAI,YAAY,wBAAwB,EAAE,CAAC;YAC7C,sEAAsE;YACtE,2CAA2C;YAC3C,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAClH,CAAC;QACD,IAAI,IAAI,YAAY,aAAa,EAAE,CAAC;YAClC,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,sCAAsC,IAAI,CAAC,OAAO,EAAE;gBAC5D,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;aACpB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,2EAA2E;IAC3E,6CAA6C;IAC7C,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,IAAI,KAAK,mBAAmB,IAAI,IAAI,KAAK,wBAAwB,EAAE,CAAC;YAC3E,sEAAsE;YACtE,6BAA6B;YAC7B,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACvG,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,mBAAmB,IAAI,IAAI,KAAK,+BAA+B,EAAE,CAAC;YAClF,uEAAuE;YACvE,oEAAoE;YACpE,gCAAgC;YAChC,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,kCAAkC,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAC1G,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;YAC3C,wEAAwE;YACxE,uEAAuE;YACvE,yEAAyE;YACzE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,2BAA2B,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACpH,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,oBAAoB,IAAI,IAAI,KAAK,wBAAwB,EAAE,CAAC;YAC5E,kEAAkE;YAClE,0DAA0D;YAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxC,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC7G,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,wBAAwB,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;YAChF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;YACjC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACzC,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC;gBACpC,MAAM,EAAE,iBAAiB;gBACzB,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3D,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC;aAC1B,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;YACvC,iEAAiE;YACjE,qEAAqE;YACrE,uEAAuE;YACvE,wCAAwC;YACxC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxC,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,2BAA2B,IAAI,GAAG,CAAC,CAAC,CAAC,uBAAuB;gBAC3E,MAAM,EAAE,cAAc;gBACtB,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;gBACrB,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC;aAC1B,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC/D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;AAC/D,CAAC"}

package/build/validation/describe-jsonld-failure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/validation/describe-jsonld-failure.test.js

@@ -0,0 +1,226 @@
+import { describeJsonLdFailure } from './describe-jsonld-failure.js';
+import { JsonLdExpansionFailedError, JsonLdInvalidShapeError } from './errors.js';
+import { ResolverHttpError, ResolverInvalidJsonError, ResolverTimedOutError } from '../resolvers/errors.js';
+import { PrivateAddressError, ResolutionFailedError } from '../node/errors.js';
+/** Builds an error shaped like jsonld.js's JsonLdError (which never sets native `cause`). */
+function jsonLdError(name, message, details) {
+    const error = new Error(message);
+    error.name = name;
+    error.details = details;
+    return error;
+}
+describe('describeJsonLdFailure', () => {
+    describe('context-fetch: typed loader failures', () => {
+        it('classifies an HTTP failure on the cause chain as context-fetch, naming URL and status', () => {
+            const http = new ResolverHttpError('https://www.w3.org/ns/credentials/v2', 429);
+            const wrapped = new JsonLdExpansionFailedError(new Error('jsonld wrapper', { cause: http }));
+            const failure = describeJsonLdFailure(wrapped);
+            expect(failure.kind).toBe('context-fetch');
+            expect(failure.detail).toContain('https://www.w3.org/ns/credentials/v2');
+            expect(failure.detail).toContain('429');
+            expect(failure.code).toBe(http.code);
+        });
+        it('classifies a timeout on the cause chain as context-fetch', () => {
+            const wrapped = new JsonLdExpansionFailedError(new ResolverTimedOutError('https://example.com/ctx', 10_000));
+            expect(describeJsonLdFailure(wrapped)).toMatchObject({ kind: 'context-fetch' });
+        });
+        it.each([
+            ['PrivateAddressError', new PrivateAddressError('https://internal.example/ctx', ['10.0.0.5'])],
+            ['ResolutionFailedError', new ResolutionFailedError('https://nxdomain.example/ctx', new Error('ENOTFOUND'))],
+        ])('collapses %s to one flat message, leaking neither the URL nor the rejection class', (_name, rejected) => {
+            const wrapped = new JsonLdExpansionFailedError(new Error('scoped context', { cause: rejected }));
+            const failure = describeJsonLdFailure(wrapped);
+            expect(failure.kind).toBe('context-fetch');
+            // One message for every UrlValidationError subclass: distinguishing
+            // "does not resolve" from "resolves privately" would be a per-hostname
+            // reconnaissance oracle. The typed detail stays on the cause chain.
+            expect(failure.detail).toBe("a remote @context URL was rejected by this service's URL policy or could not be resolved");
+            expect(failure.detail).not.toMatch(/10\.0\.0\.5|internal\.example|nxdomain\.example/);
+            expect(failure.code).toBeUndefined();
+        });
+        it('prefers the flat loader message over the URL-bearing jsonld wrapper above it (rehydrated chain shape)', () => {
+            // The real chain after validateJsonLd rehydration: the loader error
+            // hangs BENEATH jsonld.InvalidUrl, whose message contains the URL.
+            const loaderError = new PrivateAddressError('https://169.254.169.254/latest/meta-data/', ['169.254.169.254']);
+            const wrapper = jsonLdError('jsonld.InvalidUrl', 'Dereferencing a URL did not result in a valid JSON-LD object. URL: "https://169.254.169.254/latest/meta-data/".', { code: 'loading remote context failed' });
+            wrapper.cause = loaderError;
+            const wrapped = new JsonLdExpansionFailedError(wrapper);
+            const failure = describeJsonLdFailure(wrapped);
+            expect(failure.kind).toBe('context-fetch');
+            expect(failure.detail).not.toContain('169.254.169.254');
+        });
+        it('finds a typed failure at any depth of the cause chain', () => {
+            let chain = new ResolverHttpError('https://example.com/ctx', 503);
+            for (let i = 0; i < 20; i += 1) {
+                chain = new Error(`wrapper ${i}`, { cause: chain });
+            }
+            expect(describeJsonLdFailure(new JsonLdExpansionFailedError(chain))).toMatchObject({ kind: 'context-fetch' });
+        });
+    });
+    describe('context-invalid: fetched but unusable remote contexts', () => {
+        it('classifies a response body that is not JSON as context-invalid, ahead of the general resolver branch', () => {
+            const invalid = new ResolverInvalidJsonError('https://example.com/ctx', new SyntaxError('Unexpected token <'));
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(new Error('wrapper', { cause: invalid })));
+            expect(failure).toMatchObject({ kind: 'context-invalid', code: 'resolver.invalid-json' });
+            expect(failure.detail).not.toContain('Unexpected token');
+        });
+        it('classifies an unusable term-scoped remote context as context-invalid with the term', () => {
+            const processor = jsonLdError('jsonld.SyntaxError', 'Invalid JSON-LD syntax; invalid scoped context.', {
+                code: 'invalid scoped context',
+                term: 'x',
+            });
+            expect(describeJsonLdFailure(new JsonLdExpansionFailedError(processor))).toEqual({
+                kind: 'context-invalid',
+                detail: 'a remote @context response could not be used as a JSON-LD context',
+                code: 'invalid scoped context',
+                fields: { term: 'x' },
+            });
+        });
+        it('classifies a remote context chain that overflows or refers to itself as context-fetch', () => {
+            const processor = jsonLdError('jsonld.ContextUrlError', 'Maximum number of @context URLs exceeded.', {
+                code: 'context overflow',
+                url: 'https://example.com/ctx',
+            });
+            expect(describeJsonLdFailure(new JsonLdExpansionFailedError(processor))).toEqual({
+                kind: 'context-fetch',
+                detail: 'the remote @context chain could not be resolved: too many remote contexts, or a remote context refers back to itself',
+                code: 'context overflow',
+            });
+        });
+        it('classifies non-object remote context content as context-invalid, naming the code and URL', () => {
+            const processor = jsonLdError('jsonld.InvalidUrl', 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object. URL: "https://example.com/ctx".', { code: 'invalid remote context', url: 'https://example.com/ctx' });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure).toEqual({
+                kind: 'context-invalid',
+                detail: 'a remote @context response could not be used as a JSON-LD context',
+                code: 'invalid remote context',
+                url: 'https://example.com/ctx',
+            });
+        });
+        it('reports the failing @context URL from the jsonld wrapper beneath a typed loader failure', () => {
+            const wrapper = jsonLdError('jsonld.InvalidUrl', 'Dereferencing a URL did not result in a valid JSON-LD object.', {
+                code: 'loading remote context failed',
+                url: 'https://example.com/ctx',
+            });
+            wrapper.cause = new ResolverHttpError('https://example.com/ctx', 503);
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(wrapper));
+            expect(failure).toMatchObject({
+                kind: 'context-fetch',
+                code: 'resolver.http-error',
+                url: 'https://example.com/ctx',
+            });
+        });
+        it('classifies an untyped "loading remote context failed" as context-fetch without echoing the message', () => {
+            const wrapper = jsonLdError('jsonld.InvalidUrl', 'Dereferencing a URL did not result in a valid JSON-LD object.', {
+                code: 'loading remote context failed',
+                url: 'https://example.com/ctx',
+            });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(wrapper));
+            expect(failure).toEqual({
+                kind: 'context-fetch',
+                detail: 'a remote @context document could not be loaded',
+                code: 'loading remote context failed',
+                url: 'https://example.com/ctx',
+            });
+        });
+    });
+    describe('document: recognised processor shapes', () => {
+        it('extracts the safe-mode event message and offending property (real jsonld@8.3.3 shape)', () => {
+            const processor = jsonLdError('jsonld.ValidationError', 'Safe mode validation error.', {
+                event: {
+                    type: ['JsonLdEvent'],
+                    code: 'invalid property',
+                    level: 'warning',
+                    message: 'Dropping property that did not expand into an absolute IRI or keyword.',
+                    details: { property: 'unknownTerm', expandedProperty: 'unknownTerm' },
+                },
+            });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).toContain('Dropping property that did not expand');
+            expect(failure.detail).toContain('unknownTerm');
+            expect(failure).toMatchObject({ source: 'safe-mode-event' });
+            expect(failure.code).toBe('invalid property');
+            expect(failure).toMatchObject({ fields: { property: 'unknownTerm', expandedProperty: 'unknownTerm' } });
+        });
+        it('never echoes non-allowlisted event fields, which can carry credential content', () => {
+            const processor = jsonLdError('jsonld.ValidationError', 'Safe mode validation error.', {
+                event: {
+                    code: 'object with only @id',
+                    message: 'Dropping object with only @id.',
+                    details: { value: { '@id': 'urn:secret:batch-7734' } },
+                },
+            });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).not.toContain('urn:secret:batch-7734');
+            expect(failure).not.toHaveProperty('fields');
+            expect(JSON.stringify(failure)).not.toContain('urn:secret:batch-7734');
+        });
+        it('echoes only allowlisted event fields even when a non-allowlisted one is a plain string', () => {
+            const processor = jsonLdError('jsonld.ValidationError', 'Safe mode validation error.', {
+                event: {
+                    code: 'invalid property',
+                    message: 'Dropping property that did not expand into an absolute IRI or keyword.',
+                    details: { property: 'batchId', value: 'urn:secret:batch-7734' },
+                },
+            });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure).toMatchObject({ fields: { property: 'batchId' } });
+            expect(JSON.stringify(failure)).not.toContain('urn:secret:batch-7734');
+        });
+        it('never echoes a syntax-error message, which jsonld.js may interpolate caller values into', () => {
+            const processor = jsonLdError('jsonld.SyntaxError', 'Invalid JSON-LD syntax; container mapping for "secret-field-value" on term "x".', { code: 'invalid @index value', term: 'x' });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure).toEqual({
+                kind: 'document',
+                detail: 'Invalid JSON-LD syntax; invalid @index value.',
+                source: 'syntax-error',
+                code: 'invalid @index value',
+                fields: { term: 'x' },
+            });
+            expect(JSON.stringify(failure)).not.toContain('secret-field-value');
+        });
+        it('classifies a syntax error from a code and its allowlisted fields', () => {
+            const processor = jsonLdError('jsonld.SyntaxError', 'Invalid JSON-LD syntax; @type value must be a string.', {
+                code: 'invalid type value',
+            });
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).toBe('Invalid JSON-LD syntax; invalid type value.');
+            expect(failure).toMatchObject({ source: 'syntax-error' });
+            expect(failure.code).toBe('invalid type value');
+        });
+        it('keeps the typed invalid-shape diagnostic', () => {
+            const failure = describeJsonLdFailure(new JsonLdInvalidShapeError(null));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).toContain('non-null object');
+            expect(failure.code).toBe('invalid document shape');
+        });
+    });
+    describe('document: unrecognised failures never leak raw messages', () => {
+        it('returns the generic message for an untyped error instead of echoing its text', () => {
+            const leaky = new Error('internal path /srv/app/private-config.json');
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(leaky));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).toBe('the document could not be expanded as valid JSON-LD');
+            expect(failure.detail).not.toContain('/srv/app');
+        });
+        it('returns the generic message for an unknown jsonld.* error name', () => {
+            const processor = jsonLdError('jsonld.OptionsError', 'Some future message naming internals.', {});
+            const failure = describeJsonLdFailure(new JsonLdExpansionFailedError(processor));
+            expect(failure.kind).toBe('document');
+            expect(failure.detail).toBe('the document could not be expanded as valid JSON-LD');
+        });
+        it('terminates on a cyclic cause chain and classifies it as document', () => {
+            const a = new Error('a');
+            const b = new Error('b', { cause: a });
+            a.cause = b;
+            expect(describeJsonLdFailure(new JsonLdExpansionFailedError(a))).toMatchObject({
+                kind: 'document',
+                detail: 'the document could not be expanded as valid JSON-LD',
+            });
+        });
+    });
+});
+//# sourceMappingURL=describe-jsonld-failure.test.js.map

package/build/validation/describe-jsonld-failure.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-jsonld-failure.test.js","sourceRoot":"","sources":["../../src/validation/describe-jsonld-failure.test.ts"],"names":[],"mappings":"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"}

package/build/validation/errors.d.ts

@@ -0,0 +1,40 @@
+import { StructuredError, type ValidationFailure } from '../structured-error.js';
+/**
+ * Base for every JSON-LD validation diagnostic. Catch to handle any
+ * JSON-LD failure generically; catch a concrete subclass for specific handling.
+ */
+export declare class JsonLdValidationError extends StructuredError {
+}
+/** The input was not a non-null object. */
+export declare class JsonLdInvalidShapeError extends JsonLdValidationError {
+    constructor(document: unknown);
+}
+/** `jsonld.toRDF` rejected the document (malformed context, undefined terms, etc.). */
+export declare class JsonLdExpansionFailedError extends JsonLdValidationError {
+    constructor(cause: unknown);
+}
+/**
+ * Base for every JSON Schema validation diagnostic. Catch to handle any
+ * schema-validation failure generically; catch a concrete subclass for
+ * specific handling.
+ */
+export declare class SchemaValidationError extends StructuredError {
+}
+/** A schema URL could not be loaded. */
+export declare class SchemaFetchFailedError extends SchemaValidationError {
+    constructor(url: string, cause: unknown);
+}
+/** Ajv refused to compile the schema (malformed schema, duplicate `$id`, etc.). */
+export declare class SchemaCompilationFailedError extends SchemaValidationError {
+    constructor(identifier: string, cause: unknown);
+}
+/**
+ * The payload failed schema validation. Carries every Ajv `allErrors`
+ * failure across every schema in {@link failures}, each with `code`
+ * `'schema.payload-invalid'` plus the Ajv-derived `pointer`, `received`,
+ * and `expected`.
+ */
+export declare class SchemaPayloadError extends SchemaValidationError {
+    readonly failures: readonly ValidationFailure[];
+    constructor(failures: readonly ValidationFailure[]);
+}

package/build/validation/errors.js

@@ -0,0 +1,75 @@
+import { StructuredError } from '../structured-error.js';
+/**
+ * Base for every JSON-LD validation diagnostic. Catch to handle any
+ * JSON-LD failure generically; catch a concrete subclass for specific handling.
+ */
+export class JsonLdValidationError extends StructuredError {
+}
+/** The input was not a non-null object. */
+export class JsonLdInvalidShapeError extends JsonLdValidationError {
+    constructor(document) {
+        super({
+            code: 'jsonld.invalid-shape',
+            message: 'JSON-LD document must be a non-null object.',
+            received: document === null ? 'null' : typeof document,
+            expected: 'object',
+        });
+    }
+}
+/** `jsonld.toRDF` rejected the document (malformed context, undefined terms, etc.). */
+export class JsonLdExpansionFailedError extends JsonLdValidationError {
+    constructor(cause) {
+        super({
+            code: 'jsonld.expansion-failed',
+            message: 'JSON-LD expansion failed.',
+            received: cause instanceof Error ? cause.message : String(cause),
+            cause,
+        });
+    }
+}
+/**
+ * Base for every JSON Schema validation diagnostic. Catch to handle any
+ * schema-validation failure generically; catch a concrete subclass for
+ * specific handling.
+ */
+export class SchemaValidationError extends StructuredError {
+}
+/** A schema URL could not be loaded. */
+export class SchemaFetchFailedError extends SchemaValidationError {
+    constructor(url, cause) {
+        super({
+            code: 'schema.fetch-failed',
+            message: `Could not load schema from ${url}.`,
+            received: url,
+            cause,
+        });
+    }
+}
+/** Ajv refused to compile the schema (malformed schema, duplicate `$id`, etc.). */
+export class SchemaCompilationFailedError extends SchemaValidationError {
+    constructor(identifier, cause) {
+        super({
+            code: 'schema.compilation-failed',
+            message: `Could not compile schema from ${identifier}.`,
+            received: cause instanceof Error ? cause.message : String(cause),
+            cause,
+        });
+    }
+}
+/**
+ * The payload failed schema validation. Carries every Ajv `allErrors`
+ * failure across every schema in {@link failures}, each with `code`
+ * `'schema.payload-invalid'` plus the Ajv-derived `pointer`, `received`,
+ * and `expected`.
+ */
+export class SchemaPayloadError extends SchemaValidationError {
+    failures;
+    constructor(failures) {
+        super({
+            code: 'schema.payload-invalid',
+            message: `Payload failed validation against ${failures.length} rule(s).`,
+        });
+        this.failures = failures;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/validation/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/validation/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA0B,MAAM,wBAAwB,CAAC;AAEjF;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,eAAe;CAAG;AAE7D,2CAA2C;AAC3C,MAAM,OAAO,uBAAwB,SAAQ,qBAAqB;IAChE,YAAY,QAAiB;QAC3B,KAAK,CAAC;YACJ,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,6CAA6C;YACtD,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,QAAQ;YACtD,QAAQ,EAAE,QAAQ;SACnB,CAAC,CAAC;IACL,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,0BAA2B,SAAQ,qBAAqB;IACnE,YAAY,KAAc;QACxB,KAAK,CAAC;YACJ,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,2BAA2B;YACpC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAChE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,eAAe;CAAG;AAE7D,wCAAwC;AACxC,MAAM,OAAO,sBAAuB,SAAQ,qBAAqB;IAC/D,YAAY,GAAW,EAAE,KAAc;QACrC,KAAK,CAAC;YACJ,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,8BAA8B,GAAG,GAAG;YAC7C,QAAQ,EAAE,GAAG;YACb,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,4BAA6B,SAAQ,qBAAqB;IACrE,YAAY,UAAkB,EAAE,KAAc;QAC5C,KAAK,CAAC;YACJ,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,iCAAiC,UAAU,GAAG;YACvD,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAChE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,qBAAqB;IAClD,QAAQ,CAA+B;IAChD,YAAY,QAAsC;QAChD,KAAK,CAAC;YACJ,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,qCAAqC,QAAQ,CAAC,MAAM,WAAW;SACzE,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/build/validation/index.d.ts

@@ -0,0 +1,5 @@
+export { JsonLdValidationError, JsonLdInvalidShapeError, JsonLdExpansionFailedError, SchemaValidationError, SchemaFetchFailedError, SchemaCompilationFailedError, SchemaPayloadError, } from './errors.js';
+export { expandJsonLd, validateJsonLd, type JsonLdDocumentLoader, type ValidateJsonLdOptions, } from './validate-jsonld.js';
+export { validateAgainstSchemas, type SchemaReference } from './validate-against-schemas.js';
+export { describeJsonLdFailure, SAFE_EVENT_FIELDS, type JsonLdContextFailure, type JsonLdDocumentFailure, type JsonLdFailureDescription, type SafeJsonLdFields, } from './describe-jsonld-failure.js';
+export type { BundledFallbackEvent, BundledFallbackOptions } from '../bundle/fallback.js';

package/build/validation/index.js

@@ -0,0 +1,5 @@
+export { JsonLdValidationError, JsonLdInvalidShapeError, JsonLdExpansionFailedError, SchemaValidationError, SchemaFetchFailedError, SchemaCompilationFailedError, SchemaPayloadError, } from './errors.js';
+export { expandJsonLd, validateJsonLd, } from './validate-jsonld.js';
+export { validateAgainstSchemas } from './validate-against-schemas.js';
+export { describeJsonLdFailure, SAFE_EVENT_FIELDS, } from './describe-jsonld-failure.js';
+//# sourceMappingURL=index.js.map

package/build/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,cAAc,GAGf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,sBAAsB,EAAwB,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAKlB,MAAM,8BAA8B,CAAC"}

package/build/validation/validate-against-schemas.d.ts

@@ -0,0 +1,22 @@
+import type { SchemaLoader } from '../loaders/schema-loader.js';
+/**
+ * A schema reference. A string is treated as a URL and loaded via the
+ * supplied {@link SchemaLoader}; an object is used directly as the JSON
+ * Schema document. The two forms may be mixed in one call.
+ */
+export type SchemaReference = string | object;
+/**
+ * Validates a payload against one or more JSON Schemas. Ajv runs with
+ * `allErrors: true` so a single payload surfaces every validation failure
+ * per schema, and payload failures accumulate across all schemas.
+ *
+ * Fetch and compile failures are fail-fast: the first schema that cannot
+ * be loaded or compiled aborts the run. Only payload-invalid failures
+ * accumulate.
+ *
+ * @throws {SchemaFetchFailedError} if a schema URL cannot be loaded.
+ * @throws {SchemaCompilationFailedError} if Ajv refuses a schema.
+ * @throws {SchemaPayloadError} carrying every Ajv `allErrors` failure in
+ *   `failures[]` if any payload validation failed.
+ */
+export declare function validateAgainstSchemas(payload: unknown, schemas: SchemaReference[], loader: SchemaLoader): Promise<void>;