@adcp/sdk 14.4.0 → 15.2.0

package/dist/lib/auth/oauth/types.d.mts

@@ -13,8 +13,10 @@ export type { AgentConfig, AgentOAuthTokens, AgentOAuthClient };
  * Agent config storage interface
  *
  * Implement this to persist OAuth tokens back to agent configuration.
- * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim,
- * and remove OAuth fields absent from the authoritative agent snapshot.
+ * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim.
+ * For oauth_tokens, oauth_client, oauth_code_verifier and oauth_discovery_state,
+ * an own undefined property clears; omission preserves the saved field.
+ * Resource overrides and other fields retain the storage backend's semantics.
  * This allows different storage backends (file, database, memory)
  * while keeping tokens in the agent config structure.
  */
@@ -76,6 +78,11 @@ export interface OAuthProviderConfig {
     storage?: OAuthConfigStorage;
     /** Authorization flow handler */
     flowHandler: OAuthFlowHandler;
+    /**
+     * Explicitly allow fresh registration, PKCE work, redirects and automatic
+     * credential invalidation. Defaults to false; CLI factories opt in.
+     */
+    allowInteractiveAuthorization?: boolean;
     /** OAuth client metadata (required - use DEFAULT_CLIENT_METADATA as base) */
     clientMetadata: OAuthClientMetadata;
     /**

package/dist/lib/auth/oauth/types.d.ts

@@ -13,8 +13,10 @@ export type { AgentConfig, AgentOAuthTokens, AgentOAuthClient };
  * Agent config storage interface
  *
  * Implement this to persist OAuth tokens back to agent configuration.
- * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim,
- * and remove OAuth fields absent from the authoritative agent snapshot.
+ * Round-trip pending `oauth_code_verifier` and `oauth_discovery_state` verbatim.
+ * For oauth_tokens, oauth_client, oauth_code_verifier and oauth_discovery_state,
+ * an own undefined property clears; omission preserves the saved field.
+ * Resource overrides and other fields retain the storage backend's semantics.
  * This allows different storage backends (file, database, memory)
  * while keeping tokens in the agent config structure.
  */
@@ -76,6 +78,11 @@ export interface OAuthProviderConfig {
     storage?: OAuthConfigStorage;
     /** Authorization flow handler */
     flowHandler: OAuthFlowHandler;
+    /**
+     * Explicitly allow fresh registration, PKCE work, redirects and automatic
+     * credential invalidation. Defaults to false; CLI factories opt in.
+     */
+    allowInteractiveAuthorization?: boolean;
     /** OAuth client metadata (required - use DEFAULT_CLIENT_METADATA as base) */
     clientMetadata: OAuthClientMetadata;
     /**

package/dist/lib/auth/oauth/types.js

@@ -103,10 +103,11 @@ function fromMCPClientInfo(info) {
   };
 }
 function isOAuthIssuer(value) {
-  if (typeof value !== "string" || value.length === 0) return false;
+  if (typeof value !== "string" || !value || /[\u0000-\u0020\u007f\\]/.test(value)) return false;
   try {
     const url = new URL(value);
-    return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password && !url.search && !url.hash;
+    const rawAuthority = value.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i)?.[1];
+    return (url.protocol === "https:" || url.protocol === "http:") && !rawAuthority?.includes("@") && !url.username && !url.password && !url.search && !url.hash;
   } catch {
     return false;
   }

package/dist/lib/auth/oauth/types.mjs

@@ -71,10 +71,11 @@ function fromMCPClientInfo(info) {
   };
 }
 function isOAuthIssuer(value) {
-  if (typeof value !== "string" || value.length === 0) return false;
+  if (typeof value !== "string" || !value || /[\u0000-\u0020\u007f\\]/.test(value)) return false;
   try {
     const url = new URL(value);
-    return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password && !url.search && !url.hash;
+    const rawAuthority = value.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i)?.[1];
+    return (url.protocol === "https:" || url.protocol === "http:") && !rawAuthority?.includes("@") && !url.username && !url.password && !url.search && !url.hash;
   } catch {
     return false;
   }

package/dist/lib/auth/oauth/web-flow.d.mts

@@ -66,6 +66,8 @@ export interface PendingWebFlow {
     resourceOverrideSnapshot?: string | null;
     scope?: string;
     authorizationServerUrl: string;
+    /** Validated AS issuer frozen at start. Legacy rows without it cannot spend credentials. */
+    authorizationServerIssuer?: string;
     /** Persist as JSON (e.g. Postgres `jsonb`); contents are MCP SDK-typed. */
     clientInformation: OAuthClientInformation;
     createdAt: Date;

package/dist/lib/auth/oauth/web-flow.d.ts

@@ -66,6 +66,8 @@ export interface PendingWebFlow {
     resourceOverrideSnapshot?: string | null;
     scope?: string;
     authorizationServerUrl: string;
+    /** Validated AS issuer frozen at start. Legacy rows without it cannot spend credentials. */
+    authorizationServerIssuer?: string;
     /** Persist as JSON (e.g. Postgres `jsonb`); contents are MCP SDK-typed. */
     clientInformation: OAuthClientInformation;
     createdAt: Date;

package/dist/lib/auth/oauth/web-flow.js

@@ -145,6 +145,8 @@ async function startWebOAuthFlow(opts) {
     throw new import_types.OAuthError(`No OAuth metadata at ${asUrl.toString()}`, "no_authorization_server_metadata", agent.id);
   }
   (0, import_types.assertOAuthServerIssuer)(asMetadata, asUrl.toString());
+  const authorizationServerIssuer = asUrl.toString();
+  assertSavedCredentialIssuers(agent, authorizationServerIssuer);
   const resource = resourceOverride ? new URL(resourceOverride) : prm?.resource ? new URL(prm.resource) : (0, import_auth_utils.resourceUrlFromServerUrl)(new URL(agent.agent_uri));
   const baseClientMetadata = {
     ...import_types.DEFAULT_CLIENT_METADATA,
@@ -159,7 +161,8 @@ async function startWebOAuthFlow(opts) {
     asMetadata,
     clientMetadata: baseClientMetadata,
     fetchFn: guardedFetch,
-    allowConfidentialClient
+    allowConfidentialClient,
+    issuer: authorizationServerIssuer
   });
   const state = (generateState ?? defaultGenerateState)();
   const { authorizationUrl, codeVerifier } = await (0, import_auth.startAuthorization)(asUrl.toString(), {
@@ -187,6 +190,7 @@ async function startWebOAuthFlow(opts) {
     resourceOverrideSnapshot: agent.oauth_resource ?? null,
     scope,
     authorizationServerUrl: asUrl.toString(),
+    authorizationServerIssuer,
     clientInformation,
     createdAt: now,
     expiresAt,
@@ -232,11 +236,16 @@ async function completeWebOAuthFlow(opts) {
     fetchFn: guardedFetch
   });
   (0, import_types.assertOAuthServerIssuer)(asMetadata, flow.authorizationServerUrl);
+  assertFrozenIssuer(flow);
   (0, import_types.assertOAuthCredentialIssuer)(
     flow.clientInformation,
-    flow.authorizationServerUrl,
+    flow.authorizationServerIssuer,
     !!flow.clientInformation.client_secret
   );
+  if (agentStorage) {
+    agentForPersistence = await agentStorage.loadAgent(flow.agentId);
+    assertAgentUnchangedForFlow(agentForPersistence, flow);
+  }
   let tokens;
   try {
     tokens = await (0, import_auth.exchangeAuthorization)(flow.authorizationServerUrl, {
@@ -248,7 +257,7 @@ async function completeWebOAuthFlow(opts) {
       resource: flow.resource ? new URL(flow.resource) : void 0,
       fetchFn: guardedFetch
     });
-    tokens = { ...tokens, issuer: flow.authorizationServerUrl };
+    tokens = { ...tokens, issuer: flow.authorizationServerIssuer };
   } catch (err) {
     throw wrapTokenExchangeError(err);
   }
@@ -262,7 +271,8 @@ async function completeWebOAuthFlow(opts) {
     } else if (flow.resourceOverrideAction === "clear") {
       delete agentForPersistence.oauth_resource;
     }
-    delete agentForPersistence.oauth_code_verifier;
+    agentForPersistence.oauth_code_verifier = void 0;
+    agentForPersistence.oauth_discovery_state = void 0;
     await agentStorage.saveAgent(agentForPersistence);
     persisted = true;
   }
@@ -274,6 +284,20 @@ async function completeWebOAuthFlow(opts) {
     persisted
   };
 }
+function assertSavedCredentialIssuers(agent, issuer) {
+  if (agent.oauth_tokens) (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_tokens, issuer, !!agent.oauth_tokens.refresh_token);
+  if (agent.oauth_client) (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_client, issuer, !!agent.oauth_client.client_secret);
+}
+function assertFrozenIssuer(flow) {
+  if (!flow.authorizationServerIssuer) {
+    throw new import_types.OAuthError(
+      "Pending OAuth flow lacks a validated authorization-server issuer. Start a new owner sign-in.",
+      "oauth_issuer_required",
+      flow.agentId
+    );
+  }
+  (0, import_types.assertOAuthServerIssuer)({ issuer: flow.authorizationServerIssuer }, flow.authorizationServerUrl);
+}
 function assertAgentUnchangedForFlow(agent, flow) {
   if (!agent) {
     throw new AgentVanishedDuringFlowError(flow.agentId);
@@ -281,6 +305,13 @@ function assertAgentUnchangedForFlow(agent, flow) {
   if (agent.agent_uri !== flow.agentUrl) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
+  if (!agent.oauth_client) throw new AgentChangedDuringFlowError(flow.agentId);
+  const currentClient = (0, import_types.toMCPClientInfo)(agent.oauth_client);
+  for (const key of ["client_id", "client_secret", "client_secret_expires_at", "issuer"]) {
+    if (currentClient[key] !== flow.clientInformation[key]) throw new AgentChangedDuringFlowError(flow.agentId);
+  }
+  assertFrozenIssuer(flow);
+  assertSavedCredentialIssuers(agent, flow.authorizationServerIssuer);
   if (Object.prototype.hasOwnProperty.call(flow, "resourceOverrideSnapshot") && (agent.oauth_resource ?? null) !== flow.resourceOverrideSnapshot) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
@@ -416,9 +447,8 @@ function createSsrfSafeOAuthFetch(trustedFetchFn, allowHttp) {
   });
 }
 async function resolveClientInformation(args) {
-  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient } = args;
+  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient, issuer } = args;
   if (agent.oauth_client) {
-    (0, import_types.assertOAuthCredentialIssuer)(agent.oauth_client, asUrl.toString(), !!agent.oauth_client.client_secret);
     return (0, import_types.toMCPClientInfo)(agent.oauth_client);
   }
   if (!asMetadata.registration_endpoint) {
@@ -428,17 +458,20 @@ async function resolveClientInformation(args) {
       agent.id
     );
   }
-  const registration = await (0, import_auth.registerClient)(asUrl.toString(), {
+  const response = await (0, import_auth.registerClient)(asUrl.toString(), {
     metadata: asMetadata,
     clientMetadata,
     fetchFn
   });
-  const registered = { ...registration, issuer: asUrl.toString() };
+  const registered = { ...response, issuer };
   if (registered.client_secret && !allowConfidentialClient) {
     throw new ConfidentialClientNotAllowedError(agent.id);
   }
   if (agentStorage) {
-    const fresh = await agentStorage.loadAgent(agent.id) ?? agent;
+    const fresh = await agentStorage.loadAgent(agent.id);
+    if (!fresh) throw new AgentVanishedDuringFlowError(agent.id);
+    if (fresh.agent_uri !== agent.agent_uri || fresh.oauth_client) throw new AgentChangedDuringFlowError(agent.id);
+    assertSavedCredentialIssuers(fresh, issuer);
     fresh.oauth_client = (0, import_types.fromMCPClientInfo)(registered);
     await agentStorage.saveAgent(fresh);
   }

package/dist/lib/auth/oauth/web-flow.mjs

@@ -124,6 +124,8 @@ async function startWebOAuthFlow(opts) {
     throw new OAuthError(`No OAuth metadata at ${asUrl.toString()}`, "no_authorization_server_metadata", agent.id);
   }
   assertOAuthServerIssuer(asMetadata, asUrl.toString());
+  const authorizationServerIssuer = asUrl.toString();
+  assertSavedCredentialIssuers(agent, authorizationServerIssuer);
   const resource = resourceOverride ? new URL(resourceOverride) : prm?.resource ? new URL(prm.resource) : resourceUrlFromServerUrl(new URL(agent.agent_uri));
   const baseClientMetadata = {
     ...DEFAULT_CLIENT_METADATA,
@@ -138,7 +140,8 @@ async function startWebOAuthFlow(opts) {
     asMetadata,
     clientMetadata: baseClientMetadata,
     fetchFn: guardedFetch,
-    allowConfidentialClient
+    allowConfidentialClient,
+    issuer: authorizationServerIssuer
   });
   const state = (generateState ?? defaultGenerateState)();
   const { authorizationUrl, codeVerifier } = await startAuthorization(asUrl.toString(), {
@@ -166,6 +169,7 @@ async function startWebOAuthFlow(opts) {
     resourceOverrideSnapshot: agent.oauth_resource ?? null,
     scope,
     authorizationServerUrl: asUrl.toString(),
+    authorizationServerIssuer,
     clientInformation,
     createdAt: now,
     expiresAt,
@@ -211,11 +215,16 @@ async function completeWebOAuthFlow(opts) {
     fetchFn: guardedFetch
   });
   assertOAuthServerIssuer(asMetadata, flow.authorizationServerUrl);
+  assertFrozenIssuer(flow);
   assertOAuthCredentialIssuer(
     flow.clientInformation,
-    flow.authorizationServerUrl,
+    flow.authorizationServerIssuer,
     !!flow.clientInformation.client_secret
   );
+  if (agentStorage) {
+    agentForPersistence = await agentStorage.loadAgent(flow.agentId);
+    assertAgentUnchangedForFlow(agentForPersistence, flow);
+  }
   let tokens;
   try {
     tokens = await exchangeAuthorization(flow.authorizationServerUrl, {
@@ -227,7 +236,7 @@ async function completeWebOAuthFlow(opts) {
       resource: flow.resource ? new URL(flow.resource) : void 0,
       fetchFn: guardedFetch
     });
-    tokens = { ...tokens, issuer: flow.authorizationServerUrl };
+    tokens = { ...tokens, issuer: flow.authorizationServerIssuer };
   } catch (err) {
     throw wrapTokenExchangeError(err);
   }
@@ -241,7 +250,8 @@ async function completeWebOAuthFlow(opts) {
     } else if (flow.resourceOverrideAction === "clear") {
       delete agentForPersistence.oauth_resource;
     }
-    delete agentForPersistence.oauth_code_verifier;
+    agentForPersistence.oauth_code_verifier = void 0;
+    agentForPersistence.oauth_discovery_state = void 0;
     await agentStorage.saveAgent(agentForPersistence);
     persisted = true;
   }
@@ -253,6 +263,20 @@ async function completeWebOAuthFlow(opts) {
     persisted
   };
 }
+function assertSavedCredentialIssuers(agent, issuer) {
+  if (agent.oauth_tokens) assertOAuthCredentialIssuer(agent.oauth_tokens, issuer, !!agent.oauth_tokens.refresh_token);
+  if (agent.oauth_client) assertOAuthCredentialIssuer(agent.oauth_client, issuer, !!agent.oauth_client.client_secret);
+}
+function assertFrozenIssuer(flow) {
+  if (!flow.authorizationServerIssuer) {
+    throw new OAuthError(
+      "Pending OAuth flow lacks a validated authorization-server issuer. Start a new owner sign-in.",
+      "oauth_issuer_required",
+      flow.agentId
+    );
+  }
+  assertOAuthServerIssuer({ issuer: flow.authorizationServerIssuer }, flow.authorizationServerUrl);
+}
 function assertAgentUnchangedForFlow(agent, flow) {
   if (!agent) {
     throw new AgentVanishedDuringFlowError(flow.agentId);
@@ -260,6 +284,13 @@ function assertAgentUnchangedForFlow(agent, flow) {
   if (agent.agent_uri !== flow.agentUrl) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
+  if (!agent.oauth_client) throw new AgentChangedDuringFlowError(flow.agentId);
+  const currentClient = toMCPClientInfo(agent.oauth_client);
+  for (const key of ["client_id", "client_secret", "client_secret_expires_at", "issuer"]) {
+    if (currentClient[key] !== flow.clientInformation[key]) throw new AgentChangedDuringFlowError(flow.agentId);
+  }
+  assertFrozenIssuer(flow);
+  assertSavedCredentialIssuers(agent, flow.authorizationServerIssuer);
   if (Object.prototype.hasOwnProperty.call(flow, "resourceOverrideSnapshot") && (agent.oauth_resource ?? null) !== flow.resourceOverrideSnapshot) {
     throw new AgentChangedDuringFlowError(flow.agentId);
   }
@@ -395,9 +426,8 @@ function createSsrfSafeOAuthFetch(trustedFetchFn, allowHttp) {
   });
 }
 async function resolveClientInformation(args) {
-  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient } = args;
+  const { agent, agentStorage, asUrl, asMetadata, clientMetadata, fetchFn, allowConfidentialClient, issuer } = args;
   if (agent.oauth_client) {
-    assertOAuthCredentialIssuer(agent.oauth_client, asUrl.toString(), !!agent.oauth_client.client_secret);
     return toMCPClientInfo(agent.oauth_client);
   }
   if (!asMetadata.registration_endpoint) {
@@ -407,17 +437,20 @@ async function resolveClientInformation(args) {
       agent.id
     );
   }
-  const registration = await registerClient(asUrl.toString(), {
+  const response = await registerClient(asUrl.toString(), {
     metadata: asMetadata,
     clientMetadata,
     fetchFn
   });
-  const registered = { ...registration, issuer: asUrl.toString() };
+  const registered = { ...response, issuer };
   if (registered.client_secret && !allowConfidentialClient) {
     throw new ConfidentialClientNotAllowedError(agent.id);
   }
   if (agentStorage) {
-    const fresh = await agentStorage.loadAgent(agent.id) ?? agent;
+    const fresh = await agentStorage.loadAgent(agent.id);
+    if (!fresh) throw new AgentVanishedDuringFlowError(agent.id);
+    if (fresh.agent_uri !== agent.agent_uri || fresh.oauth_client) throw new AgentChangedDuringFlowError(agent.id);
+    assertSavedCredentialIssuers(fresh, issuer);
     fresh.oauth_client = fromMCPClientInfo(registered);
     await agentStorage.saveAgent(fresh);
   }

package/dist/lib/canonical-references/index.d.mts

@@ -5,7 +5,7 @@ export interface CanonicalReference {
 }
 export type CanonicalReferenceKind = 'format_schema' | 'platform_extensions' | 'generic';
 export type CanonicalReferenceStatus = 'resolved' | 'unresolvable' | 'invalid_document' | 'invalid_schema' | 'digest_mismatch' | 'blocked_unsafe_url' | 'invalid_ref';
-export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'digest_mismatch';
+export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'invalid_options' | 'aborted' | 'access_denied' | 'digest_mismatch';
 export interface CanonicalReferenceError {
     code: CanonicalReferenceErrorCode;
     message: string;
@@ -63,7 +63,25 @@ export interface CanonicalReferenceCacheOptions {
     /** Maximum estimated retained bytes. Default 32 MiB. Set to 0 to disable caching. */
     maxBytes?: number;
 }
+/** Host-owned authenticated document transport. It must enforce destination scope before I/O. */
+export interface CanonicalDocumentReader {
+    read(request: {
+        uri: string;
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        body: Uint8Array;
+        contentType?: string;
+    }>;
+}
+/** Stable, secret-free failure for an authenticated document transport. */
+export declare class CanonicalDocumentReadError extends Error {
+    readonly code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted';
+    constructor(code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted');
+}
 export interface CanonicalReferenceResolverOptions {
+    /** Private transports bypass all caches so every resolution re-authorizes. No HTTP fallback. */
+    documentReader?: CanonicalDocumentReader;
     /** Caller-owned cache. Defaults to a fresh bounded per-resolver LRU. */
     cache?: CanonicalReferenceCache;
     /** Default 5_000 ms. */

package/dist/lib/canonical-references/index.d.ts

@@ -5,7 +5,7 @@ export interface CanonicalReference {
 }
 export type CanonicalReferenceKind = 'format_schema' | 'platform_extensions' | 'generic';
 export type CanonicalReferenceStatus = 'resolved' | 'unresolvable' | 'invalid_document' | 'invalid_schema' | 'digest_mismatch' | 'blocked_unsafe_url' | 'invalid_ref';
-export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'digest_mismatch';
+export type CanonicalReferenceErrorCode = 'invalid_ref' | 'non_https_url' | 'unsafe_url' | 'redirect_blocked' | 'http_error' | 'network_error' | 'body_too_large' | 'invalid_json' | 'document_too_deep' | 'invalid_json_schema' | 'unsupported_schema_draft' | 'ref_sandbox_violation' | 'external_ref_unpinned' | 'keyword_limit_exceeded' | 'budget_exceeded' | 'invalid_options' | 'aborted' | 'access_denied' | 'digest_mismatch';
 export interface CanonicalReferenceError {
     code: CanonicalReferenceErrorCode;
     message: string;
@@ -63,7 +63,25 @@ export interface CanonicalReferenceCacheOptions {
     /** Maximum estimated retained bytes. Default 32 MiB. Set to 0 to disable caching. */
     maxBytes?: number;
 }
+/** Host-owned authenticated document transport. It must enforce destination scope before I/O. */
+export interface CanonicalDocumentReader {
+    read(request: {
+        uri: string;
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        body: Uint8Array;
+        contentType?: string;
+    }>;
+}
+/** Stable, secret-free failure for an authenticated document transport. */
+export declare class CanonicalDocumentReadError extends Error {
+    readonly code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted';
+    constructor(code: 'access_denied' | 'unsafe_url' | 'body_too_large' | 'network_error' | 'invalid_options' | 'aborted');
+}
 export interface CanonicalReferenceResolverOptions {
+    /** Private transports bypass all caches so every resolution re-authorizes. No HTTP fallback. */
+    documentReader?: CanonicalDocumentReader;
     /** Caller-owned cache. Defaults to a fresh bounded per-resolver LRU. */
     cache?: CanonicalReferenceCache;
     /** Default 5_000 ms. */

package/dist/lib/canonical-references/index.js

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var canonical_references_exports = {};
 __export(canonical_references_exports, {
+  CanonicalDocumentReadError: () => CanonicalDocumentReadError,
   canonicalReferenceCacheKey: () => canonicalReferenceCacheKey,
   createCanonicalReferenceCache: () => createCanonicalReferenceCache,
   createCanonicalReferenceResolver: () => createCanonicalReferenceResolver,
@@ -44,6 +45,18 @@ var import_sandbox_refs = require('../v2/format-schema/sandbox-refs.js');
 var import_regex_safety = require('../v2/format-schema/regex-safety.js');
 var import_strict_json = require('../signing/agent-resolver/strict-json.js');
 const Ajv2020 = require("ajv/dist/2020");
+class CanonicalDocumentReadError extends Error {
+  constructor(code) {
+    super(`Canonical document read: ${code}`);
+    this.code = code;
+    this.name = "CanonicalDocumentReadError";
+    Object.defineProperty(this, /* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError"), { value: true });
+  }
+  code;
+}
+function isCanonicalDocumentReadError(error) {
+  return !!error && typeof error === "object" && error[/* @__PURE__ */ Symbol.for("adcp.canonicalDocumentReadError")] === true;
+}
 const DEFAULT_TIMEOUT_MS = 5e3;
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 const DEFAULT_MAX_TOTAL_REF_BYTES = 8 * 1024 * 1024;
@@ -149,10 +162,13 @@ function exceedsJsonDocumentDepth(value) {
   return false;
 }
 function createCanonicalReferenceResolver(defaults = {}) {
+  if (defaults.documentReader && (!Number.isSafeInteger(defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) < 1 || (defaults.timeoutMs ?? DEFAULT_TIMEOUT_MS) > 6e4 || !Number.isSafeInteger(defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) < 1 || (defaults.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES) > 8 * 1024 * 1024))
+    throw new RangeError("Private canonical document transport limits are invalid");
   const cache = defaults.cache ?? createCanonicalReferenceCache();
   const merge = (options = {}) => ({
     ...defaults,
     ...options,
+    documentReader: defaults.documentReader ?? options.documentReader,
     cache
   });
   return {
@@ -205,7 +221,7 @@ async function fetchJsonReference(ref, options) {
   const kind = options.kind ?? "generic";
   const valid = validateRef(ref, kind, options);
   if (!valid.ok) return valid.result;
-  const cache = options.cache;
+  const cache = options.documentReader ? void 0 : options.cache;
   const cacheKey = canonicalReferenceCacheKey(ref, options);
   const cached = cache?.get(cacheKey);
   if (cached) {
@@ -223,15 +239,70 @@ async function fetchJsonReference(ref, options) {
   }
   let response;
   try {
-    response = await (0, import_ssrf_fetch.ssrfSafeFetch)(ref.uri, {
-      method: "GET",
-      headers: { accept: "application/json, application/schema+json" },
-      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
-      allowPrivateIp: options.allowPrivateNetwork === true,
-      signal: options.signal
-    });
+    if (options.documentReader) {
+      const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 6e4 || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 8 * 1024 * 1024)
+        throw new CanonicalDocumentReadError("invalid_options");
+      const controller = new AbortController();
+      const onAbort = () => controller.abort(new CanonicalDocumentReadError("aborted"));
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) onAbort();
+      let abortListener;
+      const timer = setTimeout(() => controller.abort(new CanonicalDocumentReadError("network_error")), timeoutMs);
+      try {
+        controller.signal.throwIfAborted();
+        const read = await Promise.race([
+          options.documentReader.read({ uri: ref.uri, maxBytes, signal: controller.signal }),
+          new Promise((_, reject) => {
+            abortListener = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", abortListener, { once: true });
+            if (controller.signal.aborted) abortListener();
+          })
+        ]);
+        controller.signal.throwIfAborted();
+        if (!(read?.body instanceof Uint8Array) || read.body.byteLength > maxBytes)
+          throw new CanonicalDocumentReadError("body_too_large");
+        response = {
+          status: 200,
+          body: Uint8Array.from(read.body),
+          headers: { "content-type": read.contentType ?? "" }
+        };
+      } finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        if (abortListener) controller.signal.removeEventListener("abort", abortListener);
+      }
+    } else {
+      response = await (0, import_ssrf_fetch.ssrfSafeFetch)(ref.uri, {
+        method: "GET",
+        headers: { accept: "application/json, application/schema+json" },
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+        allowPrivateIp: options.allowPrivateNetwork === true,
+        signal: options.signal
+      });
+    }
   } catch (err) {
+    if (isCanonicalDocumentReadError(err)) {
+      const code = [
+        "access_denied",
+        "unsafe_url",
+        "body_too_large",
+        "network_error",
+        "invalid_options",
+        "aborted"
+      ].includes(err.code) ? err.code : "network_error";
+      return fail(
+        kind,
+        ref,
+        cacheKey,
+        code === "unsafe_url" ? "blocked_unsafe_url" : "unresolvable",
+        code,
+        `Canonical document read failed: ${code}`,
+        { retryable: code === "network_error" }
+      );
+    }
     if (err instanceof import_ssrf_fetch.SsrfRefusedError) {
       if (err.code === "body_exceeds_limit") {
         return fail(
@@ -753,6 +824,7 @@ function countSchemaKeywords(root) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CanonicalDocumentReadError,
   canonicalReferenceCacheKey,
   createCanonicalReferenceCache,
   createCanonicalReferenceResolver,