@uncefact/untp-utils 0.1.0 → 0.3.0

package/build/validation/validate-against-schemas.js

@@ -0,0 +1,65 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SchemaCompilationFailedError, SchemaFetchFailedError, SchemaPayloadError } from './errors.js';
+function buildAjv() {
+    const ajv = new Ajv2020({ strict: false, allErrors: true, verbose: true });
+    addFormats(ajv);
+    return ajv;
+}
+/**
+ * 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 async function validateAgainstSchemas(payload, schemas, loader) {
+    const failures = [];
+    const ajv = buildAjv();
+    for (const ref of schemas) {
+        let schemaDoc;
+        let identifier;
+        if (typeof ref === 'string') {
+            identifier = ref;
+            try {
+                schemaDoc = await loader.load(ref);
+            }
+            catch (cause) {
+                throw new SchemaFetchFailedError(ref, cause);
+            }
+        }
+        else {
+            identifier = '<inline schema>';
+            schemaDoc = ref;
+        }
+        let validate;
+        try {
+            validate = ajv.compile(schemaDoc);
+        }
+        catch (cause) {
+            throw new SchemaCompilationFailedError(identifier, cause);
+        }
+        if (!validate(payload) && validate.errors) {
+            for (const ajvError of validate.errors) {
+                failures.push({
+                    code: 'schema.payload-invalid',
+                    message: ajvError.message ?? 'Schema validation failed.',
+                    pointer: ajvError.instancePath || '',
+                    received: ajvError.data,
+                    expected: ajvError.params,
+                });
+            }
+        }
+    }
+    if (failures.length > 0) {
+        throw new SchemaPayloadError(failures);
+    }
+}
+//# sourceMappingURL=validate-against-schemas.js.map

package/build/validation/validate-against-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-against-schemas.js","sourceRoot":"","sources":["../../src/validation/validate-against-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,kBAAkB,CAAC;AACvC,OAAO,UAAU,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvG,SAAS,QAAQ;IACf,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,UAAU,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAgB,EAChB,OAA0B,EAC1B,MAAoB;IAEpB,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IAEvB,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,SAAiB,CAAC;QACtB,IAAI,UAAkB,CAAC;QAEvB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,UAAU,GAAG,GAAG,CAAC;YACjB,IAAI,CAAC;gBACH,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;aAAM,CAAC;YACN,UAAU,GAAG,iBAAiB,CAAC;YAC/B,SAAS,GAAG,GAAG,CAAC;QAClB,CAAC;QAED,IAAI,QAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,4BAA4B,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YAC1C,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACvC,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,wBAAwB;oBAC9B,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,2BAA2B;oBACxD,OAAO,EAAE,QAAQ,CAAC,YAAY,IAAI,EAAE;oBACpC,QAAQ,EAAE,QAAQ,CAAC,IAAI;oBACvB,QAAQ,EAAE,QAAQ,CAAC,MAAM;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}

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

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

package/build/validation/validate-against-schemas.test.js

@@ -0,0 +1,169 @@
+import { jest } from '@jest/globals';
+import { ResolverHttpError, ResolverInvalidJsonError } from '../resolvers/errors.js';
+import { SchemaCompilationFailedError, SchemaFetchFailedError, SchemaPayloadError, SchemaValidationError, } from './errors.js';
+const resolveJsonDocument = jest.fn();
+// The real schema loader fetches through the guarded resolver; mock that
+// boundary (keeping the real error classes) so this suite exercises the real
+// loader + cache + Ajv without touching the network.
+jest.unstable_mockModule('../resolvers/index.js', () => ({
+    resolveJsonDocument,
+    ResolverHttpError,
+    ResolverInvalidJsonError,
+}));
+const { createInMemoryTtlCache } = await import('../cache/in-memory-ttl-cache.js');
+const { createSchemaLoader } = await import('../loaders/schema-loader.js');
+const { validateAgainstSchemas } = await import('./validate-against-schemas.js');
+const SCHEMA_URL_NAME = 'https://example.com/name-schema.json';
+const SCHEMA_URL_AGE = 'https://example.com/age-schema.json';
+const NAME_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+};
+const AGE_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+    properties: { age: { type: 'integer', minimum: 0 } },
+    required: ['age'],
+};
+describe('validateAgainstSchemas', () => {
+    let loader;
+    beforeEach(() => {
+        resolveJsonDocument.mockReset();
+        loader = createSchemaLoader(createInMemoryTtlCache({ ttlMs: 60_000 }));
+    });
+    function mockSchemaResponses(map) {
+        resolveJsonDocument.mockImplementation((async (url) => {
+            const schema = map[url];
+            if (!schema) {
+                throw new ResolverHttpError(url, 404);
+            }
+            return { json: schema, finalUrl: url };
+        }));
+    }
+    it('returns void when the payload passes every schema', async () => {
+        mockSchemaResponses({ [SCHEMA_URL_NAME]: NAME_SCHEMA, [SCHEMA_URL_AGE]: AGE_SCHEMA });
+        await expect(validateAgainstSchemas({ name: 'Alice', age: 30 }, [SCHEMA_URL_NAME, SCHEMA_URL_AGE], loader)).resolves.toBeUndefined();
+    });
+    describe('payload-invalid failures (accumulating)', () => {
+        it('throws SchemaPayloadError with a failure per Ajv failure', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_NAME]: NAME_SCHEMA });
+            const promise = validateAgainstSchemas({ age: 30 }, [SCHEMA_URL_NAME], loader);
+            await expect(promise).rejects.toBeInstanceOf(SchemaPayloadError);
+            await expect(promise).rejects.toMatchObject({
+                failures: expect.arrayContaining([expect.objectContaining({ code: 'schema.payload-invalid' })]),
+            });
+        });
+        it('accumulates failures across multiple schemas with allErrors', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_NAME]: NAME_SCHEMA, [SCHEMA_URL_AGE]: AGE_SCHEMA });
+            try {
+                await validateAgainstSchemas({}, [SCHEMA_URL_NAME, SCHEMA_URL_AGE], loader);
+                throw new Error('expected validateAgainstSchemas to throw');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(SchemaPayloadError);
+                expect(e.failures.length).toBeGreaterThanOrEqual(2);
+            }
+        });
+        it('populates pointer from Ajv instancePath', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_AGE]: AGE_SCHEMA });
+            try {
+                await validateAgainstSchemas({ age: -1 }, [SCHEMA_URL_AGE], loader);
+                throw new Error('expected validateAgainstSchemas to throw');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(SchemaPayloadError);
+                expect(e.failures[0].pointer).toBe('/age');
+            }
+        });
+        it('populates received from Ajv data and expected from Ajv params', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_AGE]: AGE_SCHEMA });
+            try {
+                await validateAgainstSchemas({ age: -1 }, [SCHEMA_URL_AGE], loader);
+                throw new Error('expected validateAgainstSchemas to throw');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(SchemaPayloadError);
+                const failure = e.failures[0];
+                expect(failure.received).toBe(-1);
+                expect(failure.expected).toEqual(expect.objectContaining({ comparison: '>=', limit: 0 }));
+            }
+        });
+    });
+    describe('fetch failures (fail-fast)', () => {
+        it('throws SchemaFetchFailedError when a schema cannot be loaded', async () => {
+            resolveJsonDocument.mockRejectedValue(new ResolverHttpError(SCHEMA_URL_NAME, 404));
+            await expect(validateAgainstSchemas({}, [SCHEMA_URL_NAME], loader)).rejects.toBeInstanceOf(SchemaFetchFailedError);
+        });
+        it('aborts on the first fetch failure without checking subsequent schemas', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_AGE]: AGE_SCHEMA });
+            await expect(validateAgainstSchemas({ age: 30 }, [SCHEMA_URL_NAME, SCHEMA_URL_AGE], loader)).rejects.toMatchObject({
+                name: 'SchemaFetchFailedError',
+                received: SCHEMA_URL_NAME,
+            });
+            const fetchedUrls = resolveJsonDocument.mock.calls.map((args) => args[0]);
+            expect(fetchedUrls).toContain(SCHEMA_URL_NAME);
+            expect(fetchedUrls).not.toContain(SCHEMA_URL_AGE);
+        });
+        it("wraps a custom loader's error as SchemaFetchFailedError", async () => {
+            const failingLoad = jest.fn(async () => {
+                throw new Error('loader exploded');
+            });
+            const customLoader = { load: failingLoad };
+            const error = await validateAgainstSchemas({}, [SCHEMA_URL_NAME], customLoader).catch((e) => e);
+            expect(error).toBeInstanceOf(SchemaFetchFailedError);
+            expect(error.cause).toBeInstanceOf(Error);
+        });
+        it('passes URLs to the supplied loader and validates the returned schema', async () => {
+            const load = jest.fn(async () => NAME_SCHEMA);
+            const customLoader = { load: load };
+            await expect(validateAgainstSchemas({ name: 'Alice' }, [SCHEMA_URL_NAME], customLoader)).resolves.toBeUndefined();
+            expect(load).toHaveBeenCalledWith(SCHEMA_URL_NAME);
+            expect(resolveJsonDocument).not.toHaveBeenCalled();
+        });
+    });
+    describe('compilation failures (fail-fast)', () => {
+        it('throws SchemaCompilationFailedError when the fetched schema is invalid', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_NAME]: { type: 'not-a-real-type' } });
+            await expect(validateAgainstSchemas({}, [SCHEMA_URL_NAME], loader)).rejects.toBeInstanceOf(SchemaCompilationFailedError);
+        });
+        it('throws SchemaCompilationFailedError for an inline schema that does not compile', async () => {
+            const badSchema = { type: 'not-a-real-type' };
+            await expect(validateAgainstSchemas({}, [badSchema], loader)).rejects.toBeInstanceOf(SchemaCompilationFailedError);
+            expect(resolveJsonDocument).not.toHaveBeenCalled();
+        });
+        it('attributes inline-schema compilation failure to <inline schema>', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_NAME]: NAME_SCHEMA });
+            const badInline = { type: 'not-a-real-type' };
+            const error = (await validateAgainstSchemas({ name: 'Alice' }, [SCHEMA_URL_NAME, badInline], loader).catch((e) => e));
+            expect(error).toBeInstanceOf(SchemaCompilationFailedError);
+            expect(error.received).toMatch(/.+/);
+            expect(error.message).toContain('<inline schema>');
+        });
+    });
+    describe('inline schema references', () => {
+        it('validates against an inline schema without invoking the loader', async () => {
+            await expect(validateAgainstSchemas({ name: 'Alice' }, [NAME_SCHEMA], loader)).resolves.toBeUndefined();
+            expect(resolveJsonDocument).not.toHaveBeenCalled();
+        });
+        it('throws SchemaPayloadError from an inline schema when the payload fails', async () => {
+            await expect(validateAgainstSchemas({}, [NAME_SCHEMA], loader)).rejects.toBeInstanceOf(SchemaPayloadError);
+            expect(resolveJsonDocument).not.toHaveBeenCalled();
+        });
+        it('mixes URL and inline schema references in a single call', async () => {
+            mockSchemaResponses({ [SCHEMA_URL_NAME]: NAME_SCHEMA });
+            await expect(validateAgainstSchemas({ name: 'Alice', age: 30 }, [SCHEMA_URL_NAME, AGE_SCHEMA], loader)).resolves.toBeUndefined();
+            expect(resolveJsonDocument).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('hierarchy', () => {
+        it('every concrete error extends SchemaValidationError', async () => {
+            resolveJsonDocument.mockRejectedValue(new ResolverHttpError(SCHEMA_URL_NAME, 404));
+            await expect(validateAgainstSchemas({}, [SCHEMA_URL_NAME], loader)).rejects.toBeInstanceOf(SchemaValidationError);
+            await expect(validateAgainstSchemas({}, [{ type: 'not-a-real-type' }], loader)).rejects.toBeInstanceOf(SchemaValidationError);
+            await expect(validateAgainstSchemas({}, [NAME_SCHEMA], loader)).rejects.toBeInstanceOf(SchemaValidationError);
+        });
+    });
+});
+//# sourceMappingURL=validate-against-schemas.test.js.map

package/build/validation/validate-against-schemas.test.js.map

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

package/build/validation/validate-jsonld.context-cache.test.d.ts

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

package/build/validation/validate-jsonld.context-cache.test.js

@@ -0,0 +1,32 @@
+import { jest } from '@jest/globals';
+import { createInMemoryTtlCache } from '../cache/in-memory-ttl-cache.js';
+const resolveJsonDocument = jest.fn();
+// Mock only the resolver boundary: real jsonld, real document loader, real
+// cache. This pins the seam validateJsonLd's contextCache option promises:
+// the cache outlives the per-call loader instance, so separate validateJsonLd
+// calls sharing one cache resolve each remote @context once.
+jest.unstable_mockModule('../resolvers/index.js', () => ({ resolveJsonDocument }));
+const { validateJsonLd } = await import('./validate-jsonld.js');
+const CONTEXT_URL = 'https://example.com/context';
+const DOCUMENT = { '@context': CONTEXT_URL, name: 'Acme' };
+describe('validateJsonLd contextCache reuse across calls', () => {
+    beforeEach(() => {
+        resolveJsonDocument.mockReset();
+        resolveJsonDocument.mockResolvedValue({
+            json: { '@context': { name: 'http://schema.org/name' } },
+            finalUrl: CONTEXT_URL,
+        });
+    });
+    it('resolves a remote @context once across separate calls sharing one cache', async () => {
+        const contextCache = createInMemoryTtlCache({ ttlMs: 60_000 });
+        await expect(validateJsonLd(DOCUMENT, { contextCache })).resolves.toBeUndefined();
+        await expect(validateJsonLd(DOCUMENT, { contextCache })).resolves.toBeUndefined();
+        expect(resolveJsonDocument).toHaveBeenCalledTimes(1);
+    });
+    it('re-resolves the remote @context per call without a shared cache', async () => {
+        await expect(validateJsonLd(DOCUMENT)).resolves.toBeUndefined();
+        await expect(validateJsonLd(DOCUMENT)).resolves.toBeUndefined();
+        expect(resolveJsonDocument).toHaveBeenCalledTimes(2);
+    });
+});
+//# sourceMappingURL=validate-jsonld.context-cache.test.js.map

package/build/validation/validate-jsonld.context-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-jsonld.context-cache.test.js","sourceRoot":"","sources":["../../src/validation/validate-jsonld.context-cache.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,MAAM,mBAAmB,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;AAEtC,2EAA2E;AAC3E,2EAA2E;AAC3E,8EAA8E;AAC9E,6DAA6D;AAC7D,IAAI,CAAC,mBAAmB,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC;AAEnF,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEhE,MAAM,WAAW,GAAG,6BAA6B,CAAC;AAClD,MAAM,QAAQ,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAE3D,QAAQ,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC9D,UAAU,CAAC,GAAG,EAAE;QACd,mBAAmB,CAAC,SAAS,EAAE,CAAC;QAChC,mBAAmB,CAAC,iBAAiB,CAAC;YACpC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,wBAAwB,EAAE,EAAE;YACxD,QAAQ,EAAE,WAAW;SACb,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,KAAK,IAAI,EAAE;QACvF,MAAM,YAAY,GAAG,sBAAsB,CAAuB,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACrF,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAClF,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAClF,MAAM,CAAC,mBAAmB,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;QAC/E,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAChE,MAAM,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAChE,MAAM,CAAC,mBAAmB,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/build/validation/validate-jsonld.d.ts

@@ -0,0 +1,59 @@
+import type { BundledFallbackOptions } from '../bundle/fallback.js';
+import type { TtlCache } from '../cache/ttl-cache.js';
+import type { LoadedRemoteDocument } from '../loaders/jsonld-document-loader.js';
+export interface ValidateJsonLdBuildLoaderOptions extends BundledFallbackOptions {
+    /** Whether to use safe mode for JSON-LD expansion. Defaults to true. */
+    safe?: boolean;
+    /**
+     * Optional cache, keyed by URL, for resolved remote `@context` documents.
+     * Supplying a shared cache avoids re-fetching the same contexts on every
+     * validation (e.g. the credential context on the issuance/verification
+     * hot path). Only successful loads are cached, so a URL the SSRF guard
+     * rejects is re-checked every time, while a bundled copy served after a
+     * host failure is cached like a fetched one. A successfully loaded
+     * document is cached even if expansion later rejects it.
+     */
+    contextCache?: TtlCache<LoadedRemoteDocument>;
+    documentLoader?: never;
+}
+/** A loader for a remote JSON-LD document, as {@link createJsonLdDocumentLoader} returns. */
+export type JsonLdDocumentLoader = (url: string) => Promise<LoadedRemoteDocument>;
+/**
+ * Options for {@link validateJsonLd} and {@link expandJsonLd}. Either a
+ * `documentLoader` the caller already holds (the same guarded loader shared
+ * across several operations, or a test double), or the pieces to build one
+ * from; the two are mutually exclusive at the type level, because a cache or
+ * fallback option passed beside a ready loader would be silently ignored.
+ */
+export type ValidateJsonLdOptions = ValidateJsonLdBuildLoaderOptions | {
+    safe?: boolean;
+    documentLoader: JsonLdDocumentLoader;
+    contextCache?: never;
+    bundledFallback?: never;
+    onBundledFallback?: never;
+};
+/**
+ * Catches malformed contexts, undefined terms, and structurally invalid
+ * linked data by expanding to RDF in safe mode (unless explicitly disabled).
+ *
+ * Expansion resolves every remote `@context` through a guarded document
+ * loader ({@link createJsonLdDocumentLoader}) so `@context` fetches pass the
+ * `validatePublicUrl` SSRF guard rather than jsonld.js's default unguarded
+ * Node loader. See ADR-033 §7 and issue #707.
+ *
+ * @see https://github.com/digitalbazaar/jsonld.js#safe-mode jsonld.js safe mode (a jsonld.js option, not a W3C-defined term).
+ * @see ../../../../docs/adrs/033-cvc-architecture.md ADR-033 §7 (Security considerations).
+ * @throws {JsonLdInvalidShapeError} if `document` is not a non-null object.
+ * @throws {JsonLdExpansionFailedError} if `jsonld.toRDF` rejects (which
+ *   includes a remote `@context` failing the SSRF guard; the guard's
+ *   rejection is reachable via native `.cause` hops off the thrown error,
+ *   see {@link rehydrateJsonLdCause}).
+ */
+export declare function validateJsonLd(document: unknown, options?: ValidateJsonLdOptions): Promise<void>;
+/**
+ * Expands `document` with the same guarded loader, safe mode and error
+ * contract as {@link validateJsonLd}, and returns the expanded form for a
+ * caller that displays it (the Playground's context step). Throws the same
+ * errors as {@link validateJsonLd}.
+ */
+export declare function expandJsonLd(document: unknown, options?: ValidateJsonLdOptions): Promise<unknown[]>;

package/build/validation/validate-jsonld.js

@@ -0,0 +1,126 @@
+import { JsonLdExpansionFailedError, JsonLdInvalidShapeError } from './errors.js';
+/**
+ * jsonld.js's own `JsonLdError` wraps a document loader's rejection in the
+ * proprietary `details.cause` and never sets native `Error.cause`
+ * (jsonld@8.3.3 `lib/JsonLdError.js`, loader wrap in
+ * `lib/ContextResolver.js`), so a plain `.cause` walk over a caught
+ * expansion failure dead-ends one hop early: the SSRF guard's rejection
+ * (see `createJsonLdDocumentLoader`) is reachable only via the non-standard
+ * `error.details.cause`, unlike the schema-fetch path (`schema-loader.ts`),
+ * which surfaces the same class of rejection on the native chain.
+ *
+ * A term's own remote `@context` (a JSON-LD 1.1 "scoped context") loses even
+ * that: jsonld.js resolves it through the same loader, but on failure its
+ * scoped-context branch (`lib/context.js`) discards the loader's error
+ * entirely and throws a fresh `JsonLdError` whose `details` carry no `cause`
+ * at all. `fallback` recovers the guard's rejection in that case: `toRDF`'s
+ * `documentLoader` is wrapped ({@link validateJsonLd}) to record the last
+ * error it threw during the call, and that call-scoped record is passed here
+ * as `fallback`. Because jsonld.js resolves `@context` documents one at a
+ * time and any loader throw immediately aborts the whole call (no later,
+ * unrelated loader call can follow one that failed), a recorded loader error
+ * is always the proximate cause of whatever expansion failure this function
+ * is asked to rehydrate, whether or not jsonld.js chose to keep its own
+ * reference to it.
+ *
+ * Rehydrates the recovered error (preferring `details.cause` when jsonld.js
+ * kept it) onto `error.cause` so a plain `.cause` walk reaches it. Mutates
+ * and returns the same object jsonld.js just threw for this call (safe:
+ * nothing else holds a reference to it), and only when there is something to
+ * recover and jsonld.js has not already set a `cause` itself, so a malformed
+ * `@context` that never reached the document loader (and so has nothing
+ * buried and no fallback recorded) does not gain a spurious one.
+ *
+ * @see https://github.com/uncefact/tests-untp/issues/773
+ */
+function rehydrateJsonLdCause(error, fallback) {
+    if (!(error instanceof Error) || error.cause !== undefined) {
+        return error;
+    }
+    const buried = error.details?.cause;
+    const recovered = buried !== undefined ? buried : fallback;
+    if (recovered !== undefined) {
+        error.cause = recovered;
+    }
+    return error;
+}
+/**
+ * Loads jsonld and the guarded document loader lazily, runs `operation` with
+ * a loader that records its last failure, and rethrows any rejection as a
+ * {@link JsonLdExpansionFailedError} whose cause is the loader's typed error
+ * where one was buried (see {@link rehydrateJsonLdCause}). Shared by
+ * {@link validateJsonLd} and {@link expandJsonLd}.
+ */
+async function withJsonLd(document, options, operation) {
+    if (typeof document !== 'object' || document === null) {
+        throw new JsonLdInvalidShapeError(document);
+    }
+    // Dynamic import: jsonld pulls in undici/TextDecoder which aren't
+    // available in jsdom, so we load it lazily to allow test mocking. The
+    // guarded document loader is loaded lazily for the same reason (it depends
+    // on the resolvers/node stack, which uses undici and node:dns).
+    const jsonldModule = await import('jsonld');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const jsonld = ('default' in jsonldModule ? jsonldModule.default : jsonldModule);
+    const documentLoader = options?.documentLoader ??
+        (await import('../loaders/jsonld-document-loader.js')).createJsonLdDocumentLoader({
+            cache: options?.contextCache,
+            bundledFallback: options?.bundledFallback,
+            onBundledFallback: options?.onBundledFallback,
+        });
+    // Recorded for rehydrateJsonLdCause's fallback: the last error the loader
+    // threw during this call (undefined if every fetch it made succeeded).
+    let lastLoaderError;
+    const trackedDocumentLoader = async (url) => {
+        try {
+            return await documentLoader(url);
+        }
+        catch (loaderError) {
+            lastLoaderError = loaderError;
+            throw loaderError;
+        }
+    };
+    // The cast bridges @types/jsonld, which types documentLoader with a legacy
+    // callback signature; jsonld.js itself accepts the single-argument
+    // promise-returning loader used here.
+    const processorOptions = {
+        safe: options?.safe ?? true,
+        documentLoader: trackedDocumentLoader,
+    };
+    try {
+        return await operation(jsonld, document, processorOptions);
+    }
+    catch (cause) {
+        throw new JsonLdExpansionFailedError(rehydrateJsonLdCause(cause, lastLoaderError));
+    }
+}
+/**
+ * Catches malformed contexts, undefined terms, and structurally invalid
+ * linked data by expanding to RDF in safe mode (unless explicitly disabled).
+ *
+ * Expansion resolves every remote `@context` through a guarded document
+ * loader ({@link createJsonLdDocumentLoader}) so `@context` fetches pass the
+ * `validatePublicUrl` SSRF guard rather than jsonld.js's default unguarded
+ * Node loader. See ADR-033 §7 and issue #707.
+ *
+ * @see https://github.com/digitalbazaar/jsonld.js#safe-mode jsonld.js safe mode (a jsonld.js option, not a W3C-defined term).
+ * @see ../../../../docs/adrs/033-cvc-architecture.md ADR-033 §7 (Security considerations).
+ * @throws {JsonLdInvalidShapeError} if `document` is not a non-null object.
+ * @throws {JsonLdExpansionFailedError} if `jsonld.toRDF` rejects (which
+ *   includes a remote `@context` failing the SSRF guard; the guard's
+ *   rejection is reachable via native `.cause` hops off the thrown error,
+ *   see {@link rehydrateJsonLdCause}).
+ */
+export async function validateJsonLd(document, options) {
+    await withJsonLd(document, options, (jsonld, doc, processorOptions) => jsonld.toRDF(doc, processorOptions));
+}
+/**
+ * Expands `document` with the same guarded loader, safe mode and error
+ * contract as {@link validateJsonLd}, and returns the expanded form for a
+ * caller that displays it (the Playground's context step). Throws the same
+ * errors as {@link validateJsonLd}.
+ */
+export async function expandJsonLd(document, options) {
+    return withJsonLd(document, options, (jsonld, doc, processorOptions) => jsonld.expand(doc, processorOptions));
+}
+//# sourceMappingURL=validate-jsonld.js.map

package/build/validation/validate-jsonld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-jsonld.js","sourceRoot":"","sources":["../../src/validation/validate-jsonld.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAsClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAS,oBAAoB,CAAC,KAAc,EAAE,QAAkB;IAC9D,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAI,KAAmD,CAAC,OAAO,EAAE,KAAK,CAAC;IACnF,MAAM,SAAS,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAID;;;;;;GAMG;AACH,KAAK,UAAU,UAAU,CACvB,QAAiB,EACjB,OAA0C,EAC1C,SAIe;IAEf,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,MAAM,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,kEAAkE;IAClE,sEAAsE;IACtE,2EAA2E;IAC3E,gEAAgE;IAChE,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,MAAM,MAAM,GAAG,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC,CAAE,YAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAA4B,CAAC;IACrH,MAAM,cAAc,GAClB,OAAO,EAAE,cAAc;QACvB,CAAC,MAAM,MAAM,CAAC,sCAAsC,CAAC,CAAC,CAAC,0BAA0B,CAAC;YAChF,KAAK,EAAE,OAAO,EAAE,YAAY;YAC5B,eAAe,EAAE,OAAO,EAAE,eAAe;YACzC,iBAAiB,EAAE,OAAO,EAAE,iBAAiB;SAC9C,CAAC,CAAC;IAEL,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,eAAwB,CAAC;IAC7B,MAAM,qBAAqB,GAAyB,KAAK,EAAE,GAAG,EAAE,EAAE;QAChE,IAAI,CAAC;YACH,OAAO,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,WAAW,EAAE,CAAC;YACrB,eAAe,GAAG,WAAW,CAAC;YAC9B,MAAM,WAAW,CAAC;QACpB,CAAC;IACH,CAAC,CAAC;IAEF,2EAA2E;IAC3E,mEAAmE;IACnE,sCAAsC;IACtC,MAAM,gBAAgB,GAAG;QACvB,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;QAC3B,cAAc,EAAE,qBAAqB;KACD,CAAC;IACvC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,MAAM,EAAE,QAA0B,EAAE,gBAAgB,CAAC,CAAC;IAC/E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,0BAA0B,CAAC,oBAAoB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC;IACrF,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAiB,EAAE,OAA+B;IACrF,MAAM,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAC9G,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAiB,EAAE,OAA+B;IACnF,OAAO,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,gBAAgB,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/build/validation/validate-jsonld.ssrf.test.d.ts

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

package/build/validation/validate-jsonld.ssrf.test.js

@@ -0,0 +1,108 @@
+import http from 'node:http';
+import { validateJsonLd } from './validate-jsonld.js';
+import { JsonLdExpansionFailedError } from './errors.js';
+import { UrlValidationError } from '../node/errors.js';
+/**
+ * Walks the native `Error.cause` chain from `error`, collecting every link.
+ * jsonld.js's own `JsonLdError` buries a document loader's rejection at the
+ * non-standard `details.cause` and never sets native `Error.cause`;
+ * `validateJsonLd` rehydrates it onto `error.cause` when wrapping an
+ * expansion failure (see `validate-jsonld.ts`), so a plain `.cause` walk
+ * reaches the SSRF guard's rejection the same way it does on the
+ * schema-fetch path (`schema-loader.ssrf.test.ts`).
+ */
+function nativeCauseChain(error) {
+    const chain = [];
+    let current = error;
+    while (current instanceof Error && current.cause !== undefined) {
+        chain.push(current.cause);
+        current = current.cause;
+    }
+    return chain;
+}
+/**
+ * End-to-end SSRF regression for JSON-LD expansion. Unlike `validate-jsonld.test.ts`,
+ * this suite does NOT mock `jsonld` or the resolver stack: it exercises the real
+ * `jsonld.toRDF` + guarded document loader against a live loopback server standing
+ * in for an internal service.
+ *
+ * The load-bearing assertion is that the canary server is NEVER contacted. A prior
+ * (unguarded) implementation would let jsonld.js's default Node loader fetch a
+ * private `@context` URL, hitting the canary. The guard rejects the URL before any
+ * connection, so `hits` stays 0 regardless of how the expansion ultimately fails.
+ *
+ * @see https://github.com/uncefact/tests-untp/issues/707
+ */
+describe('validateJsonLd SSRF guard (real jsonld + guarded loader)', () => {
+    let server;
+    let baseUrl;
+    let hits = 0;
+    beforeAll(async () => {
+        server = http.createServer((_req, res) => {
+            hits += 1;
+            res.setHeader('content-type', 'application/ld+json');
+            res.end(JSON.stringify({ '@context': {} }));
+        });
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+        const address = server.address();
+        baseUrl = `http://127.0.0.1:${address.port}`;
+    });
+    afterAll(async () => {
+        await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+    });
+    beforeEach(() => {
+        hits = 0;
+    });
+    it('never contacts a private @context URL during expansion', async () => {
+        const malicious = { '@context': `${baseUrl}/internal-context`, name: 'value' };
+        const error = await validateJsonLd(malicious).catch((e) => e);
+        expect(error).toBeInstanceOf(JsonLdExpansionFailedError);
+        // The rejection came from the SSRF guard, not an unrelated expansion failure.
+        expect(nativeCauseChain(error)).toContainEqual(expect.any(UrlValidationError));
+        // The security property: the loopback canary was never reached.
+        expect(hits).toBe(0);
+    });
+    it('rejects a metadata-service @context literal before any connection', async () => {
+        const malicious = { '@context': 'http://169.254.169.254/latest/meta-data', name: 'value' };
+        const error = await validateJsonLd(malicious).catch((e) => e);
+        expect(error).toBeInstanceOf(JsonLdExpansionFailedError);
+        expect(nativeCauseChain(error)).toContainEqual(expect.any(UrlValidationError));
+    });
+    it('expands a document with an inline @context without any network fetch', async () => {
+        const document = { '@context': { name: 'http://schema.org/name' }, name: 'Acme' };
+        await expect(validateJsonLd(document)).resolves.toBeUndefined();
+        expect(hits).toBe(0);
+    });
+    it('reaches the UrlValidationError by plain .cause hops, matching the schema-fetch path shape', async () => {
+        const malicious = { '@context': `${baseUrl}/internal-context`, name: 'value' };
+        const error = (await validateJsonLd(malicious).catch((e) => e));
+        // First hop: jsonld.js's own JsonLdError (still carries `.details` for
+        // callers that want the raw jsonld diagnostic).
+        expect(error.cause).toBeInstanceOf(Error);
+        expect(error.cause.name).toBe('jsonld.InvalidUrl');
+        // Second hop: the guard's rejection itself, reachable without digging
+        // into jsonld.js's proprietary `details.cause`.
+        expect(error.cause.cause).toBeInstanceOf(UrlValidationError);
+    });
+    it('never contacts a private scoped (term-level) @context URL during expansion', async () => {
+        // A term can declare its own remote @context (JSON-LD 1.1 scoped contexts).
+        // jsonld.js resolves it through the same guarded loader as a top-level
+        // @context, so it must be rejected the same way.
+        const malicious = {
+            '@context': { myTerm: { '@id': 'http://schema.org/myTerm', '@context': `${baseUrl}/internal-scoped-context` } },
+            myTerm: 'value',
+        };
+        const error = await validateJsonLd(malicious).catch((e) => e);
+        expect(error).toBeInstanceOf(JsonLdExpansionFailedError);
+        // The rejection came from the SSRF guard, reachable by plain .cause hops.
+        // jsonld.js's scoped-context branch (lib/context.js) discards the loader
+        // failure entirely and throws a fresh 'invalid scoped context' JsonLdError
+        // with no `details.cause` of its own, so this can only pass if
+        // validateJsonLd recovers the guard's rejection some other way (tracking
+        // it at the document-loader call, see `validate-jsonld.ts`).
+        expect(nativeCauseChain(error)).toContainEqual(expect.any(UrlValidationError));
+        // The security property: the loopback canary was never reached.
+        expect(hits).toBe(0);
+    });
+});
+//# sourceMappingURL=validate-jsonld.ssrf.test.js.map

package/build/validation/validate-jsonld.ssrf.test.js.map

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

package/build/validation/validate-jsonld.test.d.ts

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