@adcp/sdk 8.1.0-beta.13 → 8.1.0-beta.14

package/dist/lib/v2/format-schema/index.d.ts

@@ -1,19 +1,20 @@
 /**
- * Format-schema fetcher for AdCP 3.1's
- * `ProductFormatDeclaration.format_schema` references — the URI+digest
- * pointer to an out-of-tree JSON Schema document describing a custom
- * format's `params` and `slots` shape.
+ * Canonical reference resolver for AdCP 3.1 `format_schema` and
+ * `platform_extensions` URI+digest references.
  *
- * Use after `projectV1ProductToV2` or directly on V2 declarations whose
- * `format_kind: "custom"` carries a `format_schema` reference:
+ * Use the high-level resolver after `projectV1ProductToV2` or directly
+ * on V2 declarations. It returns structured statuses instead of
+ * throwing, keeps a caller-scoped immutable cache, resolves and compiles
+ * custom format schemas, and uses the same hardened transport for
+ * platform-extension definitions.
  *
  * ```ts
- * import { fetchFormatSchema } from '@adcp/sdk/v2/format-schema';
+ * import { createCanonicalReferenceResolver } from '@adcp/sdk/v2/format-schema';
  *
- * const { format_schema } = decl;
- * if (format_schema) {
- *   const { schema, fromCache } = await fetchFormatSchema(format_schema);
- *   // Use `schema` to validate the placement manifest at runtime.
+ * const resolver = createCanonicalReferenceResolver();
+ * const result = await resolver.resolveFormatSchema(decl.format_schema);
+ * if (result.ok) {
+ *   // Use `result.document` to validate the placement manifest.
  * }
  * ```
  *
@@ -23,4 +24,5 @@
  */
 export { fetchFormatSchema, FormatSchemaFetchError, _resetFormatSchemaCache, type FormatSchemaRef, type FormatSchemaFetchResult, type FormatSchemaFetchErrorCode, type FetchFormatSchemaOptions, type FormatSchemaCache, } from './fetch';
 export { resolveSchemaRefs, SchemaRefSandboxError, DEFAULT_MAX_REF_DEPTH, DEFAULT_MAX_REF_COUNT, DEFAULT_MIRROR_HOST, DEFAULT_MIRROR_HOSTS, DEFAULT_MAX_KEYWORDS, DEFAULT_VALIDATION_BUDGET_MS, type SchemaRefSandboxErrorCode, type ResolveSchemaRefsOptions, type ResolveSchemaRefsResult, } from './sandbox-refs';
+export { createCanonicalRefResolver, createCanonicalReferenceResolver, createMemoryCanonicalReferenceCache, resolveFormatSchema, resolvePlatformExtension, type CanonicalReferenceCache, type CanonicalRef, type CanonicalReferenceFailureResult, type CanonicalReferenceKind, type CanonicalReferenceResolvedResult, type CanonicalReferenceResolutionCode, type CanonicalReferenceResolutionResult, type CanonicalReferenceResolutionStatus, type CanonicalReferenceResolver, type CanonicalReferenceResolverOptions, type ResolveCanonicalReferenceOptions, } from './resolver';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/v2/format-schema/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,0BAA0B,EAC1B,gCAAgC,EAChC,mCAAmC,EACnC,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,+BAA+B,EACpC,KAAK,sBAAsB,EAC3B,KAAK,gCAAgC,EACrC,KAAK,gCAAgC,EACrC,KAAK,kCAAkC,EACvC,KAAK,kCAAkC,EACvC,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,GACtC,MAAM,YAAY,CAAC"}

package/dist/lib/v2/format-schema/index.js

@@ -1,20 +1,21 @@
 "use strict";
 /**
- * Format-schema fetcher for AdCP 3.1's
- * `ProductFormatDeclaration.format_schema` references — the URI+digest
- * pointer to an out-of-tree JSON Schema document describing a custom
- * format's `params` and `slots` shape.
+ * Canonical reference resolver for AdCP 3.1 `format_schema` and
+ * `platform_extensions` URI+digest references.
  *
- * Use after `projectV1ProductToV2` or directly on V2 declarations whose
- * `format_kind: "custom"` carries a `format_schema` reference:
+ * Use the high-level resolver after `projectV1ProductToV2` or directly
+ * on V2 declarations. It returns structured statuses instead of
+ * throwing, keeps a caller-scoped immutable cache, resolves and compiles
+ * custom format schemas, and uses the same hardened transport for
+ * platform-extension definitions.
  *
  * ```ts
- * import { fetchFormatSchema } from '@adcp/sdk/v2/format-schema';
+ * import { createCanonicalReferenceResolver } from '@adcp/sdk/v2/format-schema';
  *
- * const { format_schema } = decl;
- * if (format_schema) {
- *   const { schema, fromCache } = await fetchFormatSchema(format_schema);
- *   // Use `schema` to validate the placement manifest at runtime.
+ * const resolver = createCanonicalReferenceResolver();
+ * const result = await resolver.resolveFormatSchema(decl.format_schema);
+ * if (result.ok) {
+ *   // Use `result.document` to validate the placement manifest.
  * }
  * ```
  *
@@ -23,7 +24,7 @@
  * verification, immutable `uri@digest` cache).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_VALIDATION_BUDGET_MS = exports.DEFAULT_MAX_KEYWORDS = exports.DEFAULT_MIRROR_HOSTS = exports.DEFAULT_MIRROR_HOST = exports.DEFAULT_MAX_REF_COUNT = exports.DEFAULT_MAX_REF_DEPTH = exports.SchemaRefSandboxError = exports.resolveSchemaRefs = exports._resetFormatSchemaCache = exports.FormatSchemaFetchError = exports.fetchFormatSchema = void 0;
+exports.resolvePlatformExtension = exports.resolveFormatSchema = exports.createMemoryCanonicalReferenceCache = exports.createCanonicalReferenceResolver = exports.createCanonicalRefResolver = exports.DEFAULT_VALIDATION_BUDGET_MS = exports.DEFAULT_MAX_KEYWORDS = exports.DEFAULT_MIRROR_HOSTS = exports.DEFAULT_MIRROR_HOST = exports.DEFAULT_MAX_REF_COUNT = exports.DEFAULT_MAX_REF_DEPTH = exports.SchemaRefSandboxError = exports.resolveSchemaRefs = exports._resetFormatSchemaCache = exports.FormatSchemaFetchError = exports.fetchFormatSchema = void 0;
 var fetch_1 = require("./fetch");
 Object.defineProperty(exports, "fetchFormatSchema", { enumerable: true, get: function () { return fetch_1.fetchFormatSchema; } });
 Object.defineProperty(exports, "FormatSchemaFetchError", { enumerable: true, get: function () { return fetch_1.FormatSchemaFetchError; } });
@@ -37,4 +38,10 @@ Object.defineProperty(exports, "DEFAULT_MIRROR_HOST", { enumerable: true, get: f
 Object.defineProperty(exports, "DEFAULT_MIRROR_HOSTS", { enumerable: true, get: function () { return sandbox_refs_1.DEFAULT_MIRROR_HOSTS; } });
 Object.defineProperty(exports, "DEFAULT_MAX_KEYWORDS", { enumerable: true, get: function () { return sandbox_refs_1.DEFAULT_MAX_KEYWORDS; } });
 Object.defineProperty(exports, "DEFAULT_VALIDATION_BUDGET_MS", { enumerable: true, get: function () { return sandbox_refs_1.DEFAULT_VALIDATION_BUDGET_MS; } });
+var resolver_1 = require("./resolver");
+Object.defineProperty(exports, "createCanonicalRefResolver", { enumerable: true, get: function () { return resolver_1.createCanonicalRefResolver; } });
+Object.defineProperty(exports, "createCanonicalReferenceResolver", { enumerable: true, get: function () { return resolver_1.createCanonicalReferenceResolver; } });
+Object.defineProperty(exports, "createMemoryCanonicalReferenceCache", { enumerable: true, get: function () { return resolver_1.createMemoryCanonicalReferenceCache; } });
+Object.defineProperty(exports, "resolveFormatSchema", { enumerable: true, get: function () { return resolver_1.resolveFormatSchema; } });
+Object.defineProperty(exports, "resolvePlatformExtension", { enumerable: true, get: function () { return resolver_1.resolvePlatformExtension; } });
 //# sourceMappingURL=index.js.map

package/dist/lib/v2/format-schema/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAEH,iCASiB;AARf,0GAAA,iBAAiB,OAAA;AACjB,+GAAA,sBAAsB,OAAA;AACtB,gHAAA,uBAAuB,OAAA;AAQzB,+CAYwB;AAXtB,iHAAA,iBAAiB,OAAA;AACjB,qHAAA,qBAAqB,OAAA;AACrB,qHAAA,qBAAqB,OAAA;AACrB,qHAAA,qBAAqB,OAAA;AACrB,mHAAA,mBAAmB,OAAA;AACnB,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,4HAAA,4BAA4B,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAEH,iCASiB;AARf,0GAAA,iBAAiB,OAAA;AACjB,+GAAA,sBAAsB,OAAA;AACtB,gHAAA,uBAAuB,OAAA;AAQzB,+CAYwB;AAXtB,iHAAA,iBAAiB,OAAA;AACjB,qHAAA,qBAAqB,OAAA;AACrB,qHAAA,qBAAqB,OAAA;AACrB,qHAAA,qBAAqB,OAAA;AACrB,mHAAA,mBAAmB,OAAA;AACnB,oHAAA,oBAAoB,OAAA;AACpB,oHAAA,oBAAoB,OAAA;AACpB,4HAAA,4BAA4B,OAAA;AAM9B,uCAiBoB;AAhBlB,sHAAA,0BAA0B,OAAA;AAC1B,4HAAA,gCAAgC,OAAA;AAChC,+HAAA,mCAAmC,OAAA;AACnC,+GAAA,mBAAmB,OAAA;AACnB,oHAAA,wBAAwB,OAAA"}

package/dist/lib/v2/format-schema/resolver.d.ts

@@ -0,0 +1,71 @@
+import { type FormatSchemaFetchErrorCode, type FormatSchemaRef } from './fetch';
+import { type ResolveSchemaRefsOptions, type SchemaRefSandboxErrorCode } from './sandbox-refs';
+export type CanonicalReferenceKind = 'format_schema' | 'platform_extensions';
+export type CanonicalRef = FormatSchemaRef;
+export type CanonicalReferenceResolutionStatus = 'resolved' | 'invalid_ref' | 'blocked_unsafe_url' | 'digest_mismatch' | 'invalid_schema' | 'unresolvable';
+export type CanonicalReferenceResolutionCode = FormatSchemaFetchErrorCode | SchemaRefSandboxErrorCode | 'schema_dialect_unsupported' | 'schema_compile_failed' | 'schema_keyword_limit_exceeded';
+export interface CanonicalReferenceResolvedResult {
+    ok: true;
+    status: 'resolved';
+    kind: CanonicalReferenceKind;
+    ref: FormatSchemaRef;
+    /**
+     * Resolved document. For `format_schema`, every allowed `$ref` has
+     * been inlined and the result has compiled as JSON Schema. For
+     * `platform_extensions`, this is the fetched JSON object.
+     */
+    document: Record<string, unknown>;
+    /** Original digest-verified document, before `$ref` inlining. */
+    rawDocument: Record<string, unknown>;
+    /** True when returned from the caller-scoped immutable cache. */
+    fromCache: boolean;
+    /** `format_schema` only: count of `$ref` occurrences resolved. */
+    refCount?: number;
+    /** `format_schema` only: deepest transitive `$ref` depth observed. */
+    maxDepthSeen?: number;
+}
+export interface CanonicalReferenceFailureResult {
+    ok: false;
+    status: Exclude<CanonicalReferenceResolutionStatus, 'resolved'>;
+    kind: CanonicalReferenceKind;
+    ref: Partial<FormatSchemaRef>;
+    /** Stable transport/schema subreason. Same value as `code`. */
+    reason: CanonicalReferenceResolutionCode;
+    code: CanonicalReferenceResolutionCode;
+    /** True for transient network/server/cap failures callers may retry. */
+    retryable: boolean;
+    message: string;
+    httpStatus?: number;
+    details?: Record<string, unknown>;
+}
+export type CanonicalReferenceResolutionResult = CanonicalReferenceResolvedResult | CanonicalReferenceFailureResult;
+export interface CanonicalReferenceCache {
+    get(key: string): CanonicalReferenceResolvedResult | undefined;
+    set(key: string, value: CanonicalReferenceResolvedResult): void;
+}
+export interface CanonicalReferenceResolverOptions {
+    timeoutMs?: number;
+    maxBodyBytes?: number;
+    cache?: CanonicalReferenceCache;
+    maxRefDepth?: number;
+    maxRefCount?: number;
+    maxKeywords?: number;
+    allowInternalReferences?: boolean;
+    mirrorHost?: ResolveSchemaRefsOptions['mirrorHost'];
+    mirrorHosts?: ResolveSchemaRefsOptions['mirrorHosts'];
+    fetchExternal?: ResolveSchemaRefsOptions['fetchExternal'];
+}
+export interface ResolveCanonicalReferenceOptions extends CanonicalReferenceResolverOptions {
+    kind: CanonicalReferenceKind;
+}
+export interface CanonicalReferenceResolver {
+    resolveReference(ref: FormatSchemaRef, options: ResolveCanonicalReferenceOptions): Promise<CanonicalReferenceResolutionResult>;
+    resolveFormatSchema(ref: FormatSchemaRef, options?: CanonicalReferenceResolverOptions): Promise<CanonicalReferenceResolutionResult>;
+    resolvePlatformExtension(ref: FormatSchemaRef, options?: CanonicalReferenceResolverOptions): Promise<CanonicalReferenceResolutionResult>;
+}
+export declare function createMemoryCanonicalReferenceCache(): CanonicalReferenceCache;
+export declare function createCanonicalReferenceResolver(defaultOptions?: CanonicalReferenceResolverOptions): CanonicalReferenceResolver;
+export declare function resolveFormatSchema(ref: FormatSchemaRef, options?: CanonicalReferenceResolverOptions): Promise<CanonicalReferenceResolutionResult>;
+export declare function resolvePlatformExtension(ref: FormatSchemaRef, options?: CanonicalReferenceResolverOptions): Promise<CanonicalReferenceResolutionResult>;
+export declare const createCanonicalRefResolver: typeof createCanonicalReferenceResolver;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/lib/v2/format-schema/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/resolver.ts"],"names":[],"mappings":"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"}

package/dist/lib/v2/format-schema/resolver.js

@@ -0,0 +1,284 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCanonicalRefResolver = void 0;
+exports.createMemoryCanonicalReferenceCache = createMemoryCanonicalReferenceCache;
+exports.createCanonicalReferenceResolver = createCanonicalReferenceResolver;
+exports.resolveFormatSchema = resolveFormatSchema;
+exports.resolvePlatformExtension = resolvePlatformExtension;
+const _2019_1 = __importDefault(require("ajv/dist/2019"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+const json_schema_draft_07_json_1 = __importDefault(require("ajv/dist/refs/json-schema-draft-07.json"));
+const fetch_1 = require("./fetch");
+const sandbox_refs_1 = require("./sandbox-refs");
+function createMemoryCanonicalReferenceCache() {
+    const store = new Map();
+    return {
+        get: key => {
+            const cached = store.get(key);
+            return cached ? cloneResolvedResult(cached, false) : undefined;
+        },
+        set: (key, value) => {
+            store.set(key, cloneResolvedResult(value, false));
+        },
+    };
+}
+function createMemoryFormatSchemaCache() {
+    const store = new Map();
+    return {
+        get: key => store.get(key),
+        set: (key, value) => {
+            store.set(key, value);
+        },
+    };
+}
+function cacheKey(kind, ref) {
+    return `${kind}:${ref.uri}@${ref.digest}`;
+}
+function cloneJsonRecord(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function cloneResolvedResult(result, fromCache) {
+    return {
+        ...result,
+        ref: { ...result.ref },
+        document: cloneJsonRecord(result.document),
+        rawDocument: cloneJsonRecord(result.rawDocument),
+        fromCache,
+    };
+}
+function toFetchOptions(options, fetchCache) {
+    return {
+        timeoutMs: options.timeoutMs,
+        maxBodyBytes: options.maxBodyBytes,
+        allowInternalReferences: options.allowInternalReferences,
+        cache: fetchCache,
+    };
+}
+function fail(kind, ref, status, code, message, meta = {}) {
+    return {
+        ok: false,
+        status,
+        kind,
+        ref,
+        reason: code,
+        code,
+        retryable: meta.retryable ?? status === 'unresolvable',
+        message,
+        httpStatus: meta.httpStatus,
+        details: meta.details,
+    };
+}
+function mapFetchError(kind, ref, err) {
+    if (err.code === 'digest_mismatch') {
+        return fail(kind, ref, 'digest_mismatch', err.code, err.message, {
+            details: err.details,
+            retryable: false,
+        });
+    }
+    if (err.code === 'ssrf_refused' &&
+        (err.details?.code === 'dns_lookup_failed' ||
+            err.details?.code === 'dns_empty' ||
+            err.details?.code === 'body_exceeds_limit')) {
+        return fail(kind, ref, 'unresolvable', err.code, err.message, {
+            details: err.details,
+            retryable: true,
+        });
+    }
+    if (err.code === 'ssrf_refused' ||
+        err.code === 'redirect_blocked' ||
+        (err.code === 'invalid_ref' && /uri must use https/i.test(err.message))) {
+        return fail(kind, ref, 'blocked_unsafe_url', err.code, err.message, {
+            httpStatus: err.httpStatus,
+            details: err.details,
+            retryable: false,
+        });
+    }
+    if (err.code === 'invalid_ref') {
+        return fail(kind, ref, 'invalid_ref', err.code, err.message, { details: err.details, retryable: false });
+    }
+    if (err.code === 'invalid_json') {
+        return fail(kind, ref, 'invalid_schema', err.code, err.message, { details: err.details, retryable: false });
+    }
+    return fail(kind, ref, 'unresolvable', err.code, err.message, {
+        httpStatus: err.httpStatus,
+        details: err.details,
+        retryable: true,
+    });
+}
+function mapSandboxError(kind, ref, err) {
+    if (err.code === 'fetch_failed' && err.details?.transient === true) {
+        return fail(kind, ref, 'unresolvable', err.code, err.message, { details: err.details, retryable: true });
+    }
+    if (err.code === 'fetch_failed' && typeof err.details?.httpStatus === 'number') {
+        const httpStatus = err.details.httpStatus;
+        if (httpStatus >= 300 && httpStatus < 400) {
+            return fail(kind, ref, 'blocked_unsafe_url', err.code, err.message, { details: err.details, retryable: false });
+        }
+        return fail(kind, ref, 'unresolvable', err.code, err.message, {
+            details: err.details,
+            retryable: httpStatus === 404 || httpStatus >= 500,
+        });
+    }
+    const status = err.code === 'file_scheme_rejected' || err.code === 'cross_origin_rejected'
+        ? 'blocked_unsafe_url'
+        : 'invalid_schema';
+    return fail(kind, ref, status, err.code, err.message, { details: err.details, retryable: false });
+}
+const DRAFT_07_DIALECTS = new Set([
+    'http://json-schema.org/draft-07/schema',
+    'https://json-schema.org/draft-07/schema',
+]);
+const DRAFT_2019_09_DIALECTS = new Set([
+    'http://json-schema.org/draft/2019-09/schema',
+    'https://json-schema.org/draft/2019-09/schema',
+]);
+function normalizeDialect(dialect) {
+    if (!dialect)
+        return 'draft-2019-09';
+    const normalized = dialect.endsWith('#') ? dialect.slice(0, -1) : dialect;
+    if (DRAFT_07_DIALECTS.has(normalized))
+        return 'draft-07';
+    if (DRAFT_2019_09_DIALECTS.has(normalized))
+        return 'draft-2019-09';
+    return undefined;
+}
+function countSchemaKeywords(node) {
+    if (node === null || typeof node !== 'object')
+        return 0;
+    if (Array.isArray(node))
+        return node.reduce((sum, item) => sum + countSchemaKeywords(item), 0);
+    let count = 0;
+    for (const value of Object.values(node)) {
+        count += 1;
+        count += countSchemaKeywords(value);
+    }
+    return count;
+}
+function validateJsonSchema(schema, maxKeywords) {
+    const dialect = typeof schema.$schema === 'string' ? schema.$schema : undefined;
+    const normalizedDialect = normalizeDialect(dialect);
+    if (!normalizedDialect) {
+        return {
+            ok: false,
+            code: 'schema_dialect_unsupported',
+            message: `unsupported JSON Schema dialect${dialect ? `: ${dialect}` : ''}; expected Draft-07 or Draft 2019-09`,
+            details: { dialect },
+        };
+    }
+    const keywordCount = countSchemaKeywords(schema);
+    if (keywordCount > maxKeywords) {
+        return {
+            ok: false,
+            code: 'schema_keyword_limit_exceeded',
+            message: `JSON Schema keyword count ${keywordCount} exceeds limit ${maxKeywords}`,
+            details: { keywordCount, maxKeywords },
+        };
+    }
+    const ajv = new _2019_1.default({ strict: false, allErrors: true, validateSchema: true });
+    (0, ajv_formats_1.default)(ajv);
+    ajv.addMetaSchema(json_schema_draft_07_json_1.default);
+    ajv.addMetaSchema({ ...json_schema_draft_07_json_1.default, $id: 'https://json-schema.org/draft-07/schema#' });
+    const schemaToCompile = normalizedDialect === 'draft-07'
+        ? { ...schema, $schema: 'http://json-schema.org/draft-07/schema#' }
+        : { ...schema, $schema: 'https://json-schema.org/draft/2019-09/schema' };
+    try {
+        ajv.compile(schemaToCompile);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'schema_compile_failed',
+            message: err instanceof Error ? err.message : String(err),
+            details: { errors: ajv.errors?.slice(0, 10) ?? [] },
+        };
+    }
+    return { ok: true };
+}
+function createCanonicalReferenceResolver(defaultOptions = {}) {
+    const cache = defaultOptions.cache ?? createMemoryCanonicalReferenceCache();
+    const fetchCache = createMemoryFormatSchemaCache();
+    async function resolveReference(ref, options) {
+        const merged = { ...defaultOptions, ...options };
+        const kind = options.kind;
+        const key = ref && typeof ref.uri === 'string' && typeof ref.digest === 'string' ? cacheKey(kind, ref) : undefined;
+        if (key) {
+            const cached = cache.get(key);
+            if (cached)
+                return cloneResolvedResult(cached, true);
+        }
+        let fetched;
+        try {
+            fetched = await (0, fetch_1.fetchFormatSchema)(ref, toFetchOptions(merged, fetchCache));
+        }
+        catch (err) {
+            if (err instanceof fetch_1.FormatSchemaFetchError)
+                return mapFetchError(kind, ref ?? {}, err);
+            return fail(kind, ref ?? {}, 'unresolvable', 'network_error', err instanceof Error ? err.message : String(err));
+        }
+        let document = fetched.schema;
+        let refCount;
+        let maxDepthSeen;
+        if (kind === 'format_schema') {
+            try {
+                const resolved = await (0, sandbox_refs_1.resolveSchemaRefs)(document, fetched.ref.uri, {
+                    maxDepth: merged.maxRefDepth ?? sandbox_refs_1.DEFAULT_MAX_REF_DEPTH,
+                    maxRefCount: merged.maxRefCount ?? sandbox_refs_1.DEFAULT_MAX_REF_COUNT,
+                    mirrorHost: merged.mirrorHost,
+                    mirrorHosts: merged.mirrorHosts,
+                    timeoutMs: merged.timeoutMs,
+                    maxBodyBytes: merged.maxBodyBytes,
+                    allowInternalReferences: merged.allowInternalReferences,
+                    fetchExternal: merged.fetchExternal,
+                });
+                document = resolved.schema;
+                refCount = resolved.refCount;
+                maxDepthSeen = resolved.maxDepthSeen;
+            }
+            catch (err) {
+                if (err instanceof sandbox_refs_1.SchemaRefSandboxError)
+                    return mapSandboxError(kind, fetched.ref, err);
+                return fail(kind, fetched.ref, 'invalid_schema', 'fetch_failed', err instanceof Error ? err.message : String(err));
+            }
+            const schemaValidation = validateJsonSchema(document, merged.maxKeywords ?? sandbox_refs_1.DEFAULT_MAX_KEYWORDS);
+            if (!schemaValidation.ok) {
+                return fail(kind, fetched.ref, 'invalid_schema', schemaValidation.code, schemaValidation.message, {
+                    details: schemaValidation.details,
+                });
+            }
+        }
+        const resolved = {
+            ok: true,
+            status: 'resolved',
+            kind,
+            ref: fetched.ref,
+            document,
+            rawDocument: fetched.schema,
+            fromCache: false,
+            refCount,
+            maxDepthSeen,
+        };
+        if (key)
+            cache.set(key, resolved);
+        return cloneResolvedResult(resolved, false);
+    }
+    return {
+        resolveReference,
+        resolveFormatSchema(ref, options = {}) {
+            return resolveReference(ref, { ...options, kind: 'format_schema' });
+        },
+        resolvePlatformExtension(ref, options = {}) {
+            return resolveReference(ref, { ...options, kind: 'platform_extensions' });
+        },
+    };
+}
+async function resolveFormatSchema(ref, options = {}) {
+    return createCanonicalReferenceResolver(options).resolveFormatSchema(ref);
+}
+async function resolvePlatformExtension(ref, options = {}) {
+    return createCanonicalReferenceResolver(options).resolvePlatformExtension(ref);
+}
+exports.createCanonicalRefResolver = createCanonicalReferenceResolver;
+//# sourceMappingURL=resolver.js.map

package/dist/lib/v2/format-schema/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/resolver.ts"],"names":[],"mappings":"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"}

package/dist/lib/v2/format-schema/sandbox-refs.d.ts

@@ -101,6 +101,12 @@ export interface ResolveSchemaRefsOptions {
      * Hard cap on response body bytes per `$ref` fetch. Default 1 MiB.
      */
     maxBodyBytes?: number;
+    /**
+     * Caller-scoped test/dev opt-in for loopback/private HTTP `$ref`
+     * fetches. Production callers should leave this false. IMDS/link-local
+     * metadata endpoints remain blocked by `ssrfSafeFetch`.
+     */
+    allowInternalReferences?: boolean;
     /**
      * Optional custom fetcher for external `$ref` URIs. Defaults to a
      * built-in that uses `ssrfSafeFetch` with HTTPS-only + 1 MiB cap +

package/dist/lib/v2/format-schema/sandbox-refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-refs.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/sandbox-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH;;;;GAIG;AACH,MAAM,MAAM,yBAAyB;AACnC,8DAA8D;AAC5D,aAAa;AACf,wDAAwD;GACtD,sBAAsB;AACxB,8EAA8E;GAC5E,uBAAuB;AACzB,iDAAiD;GAC/C,oBAAoB;AACtB,oDAAoD;GAClD,gBAAgB;AAClB,sDAAsD;GACpD,gBAAgB;AAClB,wFAAwF;GACtF,cAAc,CAAC;AAEnB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO;CAQjE;AAED,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAuC,CAAC;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAuC5D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AA6ShD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA4BlC"}
+{"version":3,"file":"sandbox-refs.d.ts","sourceRoot":"","sources":["../../../../src/lib/v2/format-schema/sandbox-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH;;;;GAIG;AACH,MAAM,MAAM,yBAAyB;AACnC,8DAA8D;AAC5D,aAAa;AACf,wDAAwD;GACtD,sBAAsB;AACxB,8EAA8E;GAC5E,uBAAuB;AACzB,iDAAiD;GAC/C,oBAAoB;AACtB,oDAAoD;GAClD,gBAAgB;AAClB,sDAAsD;GACpD,gBAAgB;AAClB,wFAAwF;GACtF,cAAc,CAAC;AAEnB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO;CAQjE;AAED,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAuC,CAAC;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAuC5D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAoUhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA8BlC"}

package/dist/lib/v2/format-schema/sandbox-refs.js

@@ -190,8 +190,8 @@ function resolveJsonPointer(root, pointer) {
  * per-`$ref` digests pass a custom `fetchExternal` (e.g., a registry
  * lookup that hard-fails on missing digests).
  */
-function makeDefaultFetcher(timeoutMs, maxBodyBytes) {
-    const allowHttp = (0, probe_policy_1.isInternalProbesAllowed)();
+function makeDefaultFetcher(timeoutMs, maxBodyBytes, allowInternalReferences) {
+    const allowHttp = allowInternalReferences || (0, probe_policy_1.isInternalProbesAllowed)();
     return async (uri) => {
         let res;
         try {
@@ -205,12 +205,13 @@ function makeDefaultFetcher(timeoutMs, maxBodyBytes) {
         }
         catch (err) {
             if (err instanceof ssrf_fetch_1.SsrfRefusedError) {
+                const isTransient = err.code === 'dns_lookup_failed' || err.code === 'dns_empty' || err.code === 'body_exceeds_limit';
                 throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${uri}\` — SSRF guard refused: ${err.message}`, {
                     ref: uri,
-                    details: { ssrfCode: err.code },
+                    details: { ssrfCode: err.code, transient: isTransient },
                 });
             }
-            throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${uri}\` — ${err instanceof Error ? err.message : String(err)}`, { ref: uri });
+            throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${uri}\` — ${err instanceof Error ? err.message : String(err)}`, { ref: uri, details: { transient: true } });
         }
         if (res.status >= 300 && res.status < 400) {
             throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${uri}\` — HTTP redirect ${res.status} (auto-follow disabled)`, {
@@ -221,7 +222,7 @@ function makeDefaultFetcher(timeoutMs, maxBodyBytes) {
         if (res.status < 200 || res.status >= 300) {
             throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${uri}\` — HTTP ${res.status}`, {
                 ref: uri,
-                details: { httpStatus: res.status },
+                details: { httpStatus: res.status, transient: res.status >= 500 },
             });
         }
         let parsed;
@@ -240,7 +241,7 @@ function makeDefaultFetcher(timeoutMs, maxBodyBytes) {
 /**
  * Validate that an external (non-`#/`) `$ref` target is in the
  * allowed set: same-origin as parent OR under the AAO mirror namespace.
- * Returns the normalized target origin on success; throws otherwise.
+ * Returns the absolute target URI on success; throws otherwise.
  */
 function assertRefAllowed(ref, ctx) {
     if (ref.toLowerCase().startsWith('file:')) {
@@ -248,18 +249,25 @@ function assertRefAllowed(ref, ctx) {
             ref,
         });
     }
-    const target = normalizeOrigin(ref);
+    let targetUri;
+    try {
+        targetUri = new URL(ref, ctx.currentUri).href;
+    }
+    catch {
+        throw new SchemaRefSandboxError('invalid_ref', `\`$ref: ${ref}\` — could not parse as a URI`, { ref });
+    }
+    const target = normalizeOrigin(targetUri);
     if (!target) {
         throw new SchemaRefSandboxError('invalid_ref', `\`$ref: ${ref}\` — could not parse as a URI`, { ref });
     }
     // Same-origin?
     if (target.origin === ctx.parentOrigin.origin) {
-        return target;
+        return targetUri;
     }
     // AAO mirror namespace? Spec is `https://` only — `http://` mirror
     // refs are rejected even when the host matches.
-    if (ctx.mirrorHosts.has(target.hostname) && ref.toLowerCase().startsWith('https://')) {
-        return target;
+    if (ctx.mirrorHosts.has(target.hostname) && targetUri.toLowerCase().startsWith('https://')) {
+        return targetUri;
     }
     const mirrorList = [...ctx.mirrorHosts].join(', ');
     throw new SchemaRefSandboxError('cross_origin_rejected', `\`$ref: ${ref}\` — not same-origin as parent (${ctx.parentOrigin.origin}) and not under an AAO mirror (${mirrorList})`, { ref, details: { parentOrigin: ctx.parentOrigin.origin, targetOrigin: target.origin } });
@@ -328,20 +336,31 @@ async function walk(node, depth, ctx) {
             // Parent digest is the trust anchor; same-origin / mirror refs
             // inherit trust. Callers wanting per-`$ref` digest verification
             // pass a custom `fetchExternal` that enforces it.
-            assertRefAllowed(ref, ctx);
+            const refUri = assertRefAllowed(ref, ctx);
             let body;
-            const cached = ctx.externalCache.get(ref);
+            const cached = ctx.externalCache.get(refUri);
             if (cached) {
                 body = cached;
             }
             else {
-                body = await ctx.fetchExternal(ref);
-                ctx.externalCache.set(ref, body);
+                try {
+                    body = await ctx.fetchExternal(refUri);
+                }
+                catch (err) {
+                    if (err instanceof SchemaRefSandboxError)
+                        throw err;
+                    throw new SchemaRefSandboxError('fetch_failed', `\`$ref: ${refUri}\` — ${err instanceof Error ? err.message : String(err)}`, {
+                        ref: refUri,
+                        details: { transient: true },
+                    });
+                }
+                ctx.externalCache.set(refUri, body);
             }
             // External fetch opens a new document layer. We treat each
             // external fetch as one depth step.
             const refCtx = {
                 ...ctx,
+                currentUri: refUri,
                 // The fetched document becomes the parent for its own intra-doc
                 // pointers. Same-origin checks for its own external $refs still
                 // use the ORIGINAL parent origin (the trust root). Per spec the
@@ -395,13 +414,15 @@ async function resolveSchemaRefs(schema, parentUri, options = {}) {
     }
     const timeoutMs = options.timeoutMs ?? 5_000;
     const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+    const allowInternalReferences = options.allowInternalReferences === true;
     const ctx = {
         parentRoot: schema,
+        currentUri: parentUri,
         parentOrigin,
         mirrorHosts: new Set((options.mirrorHosts ?? (options.mirrorHost ? [options.mirrorHost] : exports.DEFAULT_MIRROR_HOSTS)).map(h => h.toLowerCase())),
         maxDepth: options.maxDepth ?? exports.DEFAULT_MAX_REF_DEPTH,
         maxRefCount: options.maxRefCount ?? exports.DEFAULT_MAX_REF_COUNT,
-        fetchExternal: options.fetchExternal ?? makeDefaultFetcher(timeoutMs, maxBodyBytes),
+        fetchExternal: options.fetchExternal ?? makeDefaultFetcher(timeoutMs, maxBodyBytes, allowInternalReferences),
         externalCache: new Map(),
         count: { value: 0 },
         maxDepthSeen: { value: 0 },