@oomol-lab/open-connector 1.9.1 → 1.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-connector",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Embeddable Open Connector runtime for Node.js and Bun.",
   "license": "Apache-2.0",
   "type": "module",

package/src/connection-error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error with a stable code suitable for HTTP responses.
+ */
+export declare class ConnectionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/src/connection-error.js

@@ -0,0 +1,10 @@
+/**
+ * Error with a stable code suitable for HTTP responses.
+ */
+export class ConnectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

package/src/connection-service.d.ts

@@ -1,4 +1,5 @@
 import type { CatalogStore } from "./catalog-store.ts";
+import type { IConnectionStore, StoredConnection, StoredSaasConnection, SaasConnectionReference } from "./connection-store.ts";
 import type { ProviderHttpDispatchOptions } from "./core/provider-http-dispatch.ts";
 import type { AuthType, CredentialProfile, ResolvedCredential, RuntimeLogger } from "./core/types.ts";
 import type { MarketplacePricing, MarketplaceService } from "./marketplace/marketplace-service.ts";
@@ -51,34 +52,6 @@ export interface ConnectionServiceOptions {
     logger?: RuntimeLogger;
     marketplace?: MarketplaceService;
 }
-export interface SaasConnectionReference {
-    managedProjectId: string;
-    providerConfigId: string;
-    externalUserId: string;
-    connectedAccountId: string;
-    localRequestId: string;
-}
-export interface StoredSaasConnection {
-    source: "saas";
-    credential?: never;
-    id: string;
-    revision: string;
-    service: string;
-    connectionName: string;
-    reference: SaasConnectionReference;
-    profile: CredentialProfile;
-    status: "active" | "reauth_required";
-    comment: string | null;
-}
-export type StoredConnection = StoredLocalConnection | StoredSaasConnection;
-export interface StoredLocalConnection {
-    source?: "local";
-    id: string;
-    revision: string;
-    service: string;
-    connectionName: string;
-    credential: ResolvedCredential;
-}
 export interface DisconnectOptions {
     /**
      * `true` also revokes the OAuth grant at the provider once the credential is
@@ -111,18 +84,6 @@ interface SaasExecutionConnection {
     summary: ManagedConnectionSummary;
     reference: SaasConnectionReference;
 }
-/**
- * Storage contract for local provider connections.
- */
-export interface IConnectionStore {
-    get(service: string, connectionName: string): Promise<StoredConnection | undefined>;
-    getRetirementGeneration(service: string, connectionName: string): Promise<string>;
-    setIfCurrentGeneration(service: string, connectionName: string, credential: ResolvedCredential, retirementGeneration: string): Promise<StoredLocalConnection | undefined>;
-    set(service: string, connectionName: string, credential: ResolvedCredential): Promise<StoredLocalConnection>;
-    updateCredential(input: StoredLocalConnection, refresh?: boolean): Promise<boolean>;
-    delete(service: string, connectionName: string): Promise<void>;
-    list(): Promise<StoredConnection[]>;
-}
 type OAuthCredential = Extract<ResolvedCredential, {
     authType: "oauth2";
 }>;
@@ -135,7 +96,7 @@ type OAuthCredential = Extract<ResolvedCredential, {
 export declare class ConnectionService {
     private readonly providerHttpDispatch?;
     private readonly catalog;
-    private readonly oauthCredentialRefreshes;
+    private readonly credentials;
     private readonly oauthCredentials?;
     private readonly providerLoader;
     private readonly store;
@@ -208,8 +169,6 @@ export declare class ConnectionService {
     private validateCustomCredential;
     private validateOAuthCredential;
     private createValidatorOptions;
-    private resolveOAuthCredential;
-    private refreshOAuthCredential;
     private runCredentialValidator;
     private assertNotCancelled;
     private buildCredentialRuntimeData;
@@ -220,11 +179,4 @@ export declare class ConnectionService {
     private createDefaultDisplayName;
 }
 export declare function normalizeConnectionName(value: string | undefined): string;
-/**
- * Error with a stable code suitable for HTTP responses.
- */
-export declare class ConnectionError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
 export {};

package/src/connection-service.js

@@ -1,32 +1,10 @@
+import { ConnectionError } from "./connection-error.js";
 import { normalizeCredentialValues } from "./core/credential-fields.js";
 import { apiKeyCredentialFields } from "./core/provider-setup.js";
+import { CredentialResolver, isOAuthCredentialExpired } from "./credential-resolver.js";
 import { providerFetch, ProviderDispatchRequestError, withProviderHttpDispatchResult, } from "./providers/provider-runtime.js";
 export const defaultConnectionName = "default";
 const connectionNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
-const OAUTH_REFRESH_PERSIST_ATTEMPTS = 3;
-/**
- * Lays a refresh result onto the connection's current credential. A refresh owns the token
- * fields and the metadata keys it changed; everything else on `current` belongs to whoever
- * bumped the revision and is kept.
- */
-function mergeRefreshedOAuthCredential(current, spent, refreshed) {
-    const metadata = { ...current.metadata };
-    for (const [key, value] of Object.entries(refreshed.metadata)) {
-        if (JSON.stringify(value) !== JSON.stringify(spent.metadata[key]))
-            metadata[key] = value;
-    }
-    // A successful refresh proves the authorization is live, so a concurrent refusal's mark is stale.
-    delete metadata.oauthReauthRequired;
-    return {
-        ...current,
-        accessToken: refreshed.accessToken,
-        tokenType: refreshed.tokenType,
-        expiresAt: refreshed.expiresAt,
-        refreshToken: refreshed.refreshToken,
-        providerSecret: refreshed.providerSecret,
-        metadata,
-    };
-}
 /**
  * Coordinates local provider connection state.
  *
@@ -36,7 +14,7 @@ function mergeRefreshedOAuthCredential(current, spent, refreshed) {
 export class ConnectionService {
     providerHttpDispatch;
     catalog;
-    oauthCredentialRefreshes = new Map();
+    credentials;
     oauthCredentials;
     providerLoader;
     store;
@@ -48,6 +26,7 @@ export class ConnectionService {
         this.oauthCredentials = input.oauthCredentials;
         this.providerLoader = input.providerLoader;
         this.store = input.store;
+        this.credentials = new CredentialResolver(input);
         this.logger = input.logger;
         this.marketplace = input.marketplace;
     }
@@ -138,10 +117,7 @@ export class ConnectionService {
         }
         if (stored?.source === "saas")
             return { kind: "saas", summary: this.createManagedConnectionSummary(stored), reference: stored.reference };
-        let credential = stored?.credential;
-        if (stored?.credential.authType === "oauth2") {
-            credential = await this.resolveOAuthCredential(stored, stored.credential);
-        }
+        let credential = stored ? await this.credentials.resolve(stored) : undefined;
         credential ??= this.supportsAuth(provider, "no_auth") ? { authType: "no_auth" } : undefined;
         const summary = stored
             ? this.createConfiguredConnectionSummary(provider, stored.id, name, credential)
@@ -161,9 +137,7 @@ export class ConnectionService {
         if (stored?.source === "saas")
             throw new ConnectionError("unsupported_auth_type", "SaaS credentials are not available locally.");
         if (stored) {
-            return stored.credential.authType === "oauth2"
-                ? await this.resolveOAuthCredential(stored, stored.credential)
-                : stored.credential;
+            return this.credentials.resolve(stored);
         }
         if (connectionName && !this.supportsAuth(provider, "no_auth")) {
             throw new ConnectionError("connection_not_found", `${service} connection not found: ${name}.`);
@@ -514,87 +488,6 @@ export class ConnectionService {
             signal,
         };
     }
-    async resolveOAuthCredential(connection, credential) {
-        const service = connection.service;
-        if (credential.metadata.oauthReauthRequired === true) {
-            throw new ConnectionError("oauth_reauth_required", `OAuth authorization is no longer valid. Reconnect ${service}.`);
-        }
-        if (!isOAuthCredentialExpired(credential)) {
-            return credential;
-        }
-        if (!credential.refreshToken) {
-            throw new ConnectionError("oauth_token_expired", `${service} OAuth access token expired and no refresh token is available. Reconnect ${service}.`);
-        }
-        if (!this.oauthCredentials) {
-            throw new ConnectionError("oauth_refresh_unavailable", `${service} OAuth access token expired and this runtime cannot refresh it.`);
-        }
-        // Single-flight on the refresh token being spent, not the row revision: a single-use
-        // (rotating) refresh token must reach the provider once even when an unrelated write
-        // bumps the revision mid-refresh. A new authorization must refresh independently,
-        // even when the provider reuses the same refresh token across reconnects.
-        const refreshKey = JSON.stringify([
-            connection.id,
-            credential.refreshToken,
-            credential.metadata.oauthAuthorizationId,
-        ]);
-        const currentRefresh = this.oauthCredentialRefreshes.get(refreshKey);
-        if (currentRefresh) {
-            return currentRefresh;
-        }
-        const refresh = this.refreshOAuthCredential(connection, credential, this.oauthCredentials);
-        this.oauthCredentialRefreshes.set(refreshKey, refresh);
-        try {
-            return await refresh;
-        }
-        finally {
-            if (this.oauthCredentialRefreshes.get(refreshKey) === refresh) {
-                this.oauthCredentialRefreshes.delete(refreshKey);
-            }
-        }
-    }
-    async refreshOAuthCredential(connection, credential, refresher) {
-        const { id, revision, service, connectionName } = connection;
-        let nextCredential;
-        try {
-            nextCredential = await withProviderHttpDispatchResult({ operation: "oauth", service, connectionId: id, connectionName }, () => refresher.refresh(service, credential), this.providerHttpDispatch);
-        }
-        catch (error) {
-            if (error instanceof ConnectionError && error.code === "oauth_reauth_required") {
-                // The revision fence prevents a late refusal from marking a replacement authorization as expired.
-                await this.store.updateCredential({
-                    id,
-                    revision,
-                    service,
-                    connectionName,
-                    credential: { ...credential, metadata: { ...credential.metadata, oauthReauthRequired: true } },
-                }, true);
-            }
-            throw error;
-        }
-        // The provider has now spent the old refresh token. With rotating single-use refresh
-        // tokens, discarding `nextCredential` loses the connection for good, so a lost
-        // revision race re-reads the row and lands the refreshed token fields on the latest
-        // revision, as long as that row still holds the credential this refresh spent.
-        let target = { ...connection, source: "local", credential: nextCredential };
-        for (let attempt = 0; attempt < OAUTH_REFRESH_PERSIST_ATTEMPTS; attempt++) {
-            if (await this.store.updateCredential(target, true))
-                return target.credential;
-            const current = await this.store.get(service, connectionName);
-            if (current?.source === "saas" ||
-                current?.id !== id ||
-                current.credential.authType !== "oauth2" ||
-                current.credential.refreshToken !== credential.refreshToken ||
-                current.credential.metadata.oauthAuthorizationId !== credential.metadata.oauthAuthorizationId) {
-                // Deleted, converted, reconnected, or already rotated elsewhere: never overwrite it.
-                break;
-            }
-            target = {
-                ...current,
-                credential: mergeRefreshedOAuthCredential(current.credential, credential, nextCredential),
-            };
-        }
-        throw new ConnectionError("connection_not_found", `${service} connection changed while its OAuth credential was refreshing. Retry the action.`);
-    }
     async runCredentialValidator(service, validate, signal) {
         this.assertNotCancelled(signal);
         try {
@@ -686,13 +579,6 @@ export class ConnectionService {
         return `${provider.displayName} ${authType === "api_key" ? "API Key" : "Credential"}`;
     }
 }
-function isOAuthCredentialExpired(credential) {
-    if (!credential.expiresAt) {
-        return false;
-    }
-    const expiresAt = Date.parse(credential.expiresAt);
-    return Number.isFinite(expiresAt) && expiresAt <= Date.now() + 60_000;
-}
 export function normalizeConnectionName(value) {
     const name = value?.trim() || defaultConnectionName;
     if (!connectionNamePattern.test(name)) {
@@ -710,16 +596,6 @@ function readLegacyString(metadata, key) {
     const value = metadata?.[key];
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
-/**
- * Error with a stable code suitable for HTTP responses.
- */
-export class ConnectionError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-    }
-}
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/src/connection-store.d.ts

@@ -0,0 +1,41 @@
+import type { CredentialProfile, ResolvedCredential } from "./core/types.ts";
+export interface SaasConnectionReference {
+    managedProjectId: string;
+    providerConfigId: string;
+    externalUserId: string;
+    connectedAccountId: string;
+    localRequestId: string;
+}
+export interface StoredSaasConnection {
+    source: "saas";
+    credential?: never;
+    id: string;
+    revision: string;
+    service: string;
+    connectionName: string;
+    reference: SaasConnectionReference;
+    profile: CredentialProfile;
+    status: "active" | "reauth_required";
+    comment: string | null;
+}
+export type StoredConnection = StoredLocalConnection | StoredSaasConnection;
+export interface StoredLocalConnection {
+    source?: "local";
+    id: string;
+    revision: string;
+    service: string;
+    connectionName: string;
+    credential: ResolvedCredential;
+}
+/**
+ * Storage contract for local and SaaS provider connections.
+ */
+export interface IConnectionStore {
+    get(service: string, connectionName: string): Promise<StoredConnection | undefined>;
+    getRetirementGeneration(service: string, connectionName: string): Promise<string>;
+    setIfCurrentGeneration(service: string, connectionName: string, credential: ResolvedCredential, retirementGeneration: string): Promise<StoredLocalConnection | undefined>;
+    set(service: string, connectionName: string, credential: ResolvedCredential): Promise<StoredLocalConnection>;
+    updateCredential(input: StoredLocalConnection, refresh?: boolean): Promise<boolean>;
+    delete(service: string, connectionName: string): Promise<void>;
+    list(): Promise<StoredConnection[]>;
+}

package/src/connection-store.js

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

package/src/core/guarded-fetch.d.ts

@@ -1,4 +1,5 @@
 import type { GuardedHttpDispatcher } from "./provider-http-dispatch.ts";
+import type { ProviderNetworkPolicy } from "./provider-network-policy.ts";
 /**
  * Single resolved address returned by a DNS lookup, mirroring the shape of
  * `node:dns` `lookup(hostname, { all: true })` entries.
@@ -13,6 +14,8 @@ export interface ResolvedAddress {
  */
 export type GuardedFetchDnsLookup = (hostname: string) => Promise<ResolvedAddress[]>;
 export interface GuardedFetchOptions {
+    /** Bind runtime policy; private targets still require the transport's allowPrivateNetwork opt-in. */
+    network?: ProviderNetworkPolicy;
     /** Optional dispatcher at the screened raw-transport seam; every redirect hop passes through it. */
     dispatchAttempt?: GuardedHttpDispatcher;
     /**

package/src/core/guarded-fetch.js

@@ -1,3 +1,4 @@
+import { withProviderNetworkPolicy } from "./provider-network-policy.js";
 import { assertPublicHttpUrl, classifyIpAddress, isEgressTrustedHost, isIpAddress, isIpv4Address } from "./request.js";
 // Match the platform default for `redirect: "follow"` (undici/browsers follow up
 // to 20 hops) so wrapping the transport does not fail legitimate long redirect
@@ -77,6 +78,8 @@ export const crossOriginSafeHeaders = new Set([
 const bodyHeaders = ["content-encoding", "content-language", "content-length", "content-location", "content-type"];
 /** Base transport behind each guarded fetch (undefined = global fetch) so re-wrapping never stacks guards. */
 const guardedFetchBases = new WeakMap();
+/** Preserve an explicitly bound runtime policy when a provider rewraps its transport. */
+const guardedFetchPolicies = new WeakMap();
 /** Retain admission when a caller replaces the egress policy without stacking guards. */
 const guardedFetchDispatchers = new WeakMap();
 let defaultLookupOverridden = false;
@@ -136,10 +139,11 @@ export function unwrapGuardedFetch(fetcher) {
  */
 export function createGuardedFetch(options = {}) {
     const baseFetch = unwrapGuardedFetch(options.fetch);
+    const network = options.network ?? (options.fetch && guardedFetchPolicies.get(options.fetch));
     const dispatchAttempt = options.dispatchAttempt ?? (options.fetch && guardedFetchDispatchers.get(options.fetch));
     const createError = options.createError ?? ((message) => new TypeError(message));
     const maxRedirects = options.maxRedirects ?? defaultMaxRedirects;
-    const guardedFetch = (async (input, init) => {
+    const performFetch = (async (input, init) => {
         const transport = baseFetch ?? globalThis.fetch;
         const requestId = dispatchAttempt ? crypto.randomUUID() : "";
         let redirectHop = 0;
@@ -251,6 +255,9 @@ export function createGuardedFetch(options = {}) {
             url = guardedNext;
         }
     });
+    const guardedFetch = (network ? (input, init) => withProviderNetworkPolicy(network, () => performFetch(input, init)) : performFetch);
+    if (network)
+        guardedFetchPolicies.set(guardedFetch, network);
     guardedFetchBases.set(guardedFetch, baseFetch);
     guardedFetchDispatchers.set(guardedFetch, dispatchAttempt);
     return guardedFetch;

package/src/core/json-schema.d.ts

@@ -6,12 +6,19 @@ export type JsonSchemaOptions = {
     description?: string;
     default?: unknown;
     format?: string;
+    not?: JsonSchema;
 };
 type ObjectOptions = JsonSchemaOptions & {
     required?: string[];
     optional?: readonly string[];
     additionalProperties?: boolean | JsonSchema;
     defs?: Record<string, JsonSchema>;
+    minProperties?: number;
+    maxProperties?: number;
+    propertyNames?: JsonSchema;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
 };
 type ArrayOptions = JsonSchemaOptions & {
     minItems?: number;
@@ -28,6 +35,7 @@ type NumberOptions = JsonSchemaOptions & {
     minimum?: number;
     maximum?: number;
     exclusiveMinimum?: number;
+    multipleOf?: number;
 };
 /**
  * JSON Schema helpers for provider action contracts.
@@ -48,7 +56,7 @@ export declare const jsonSchema: {
     unknown(description: string): JsonSchema;
     url(description: string): JsonSchema;
     email(description: string, options?: Omit<StringOptions, "description" | "format">): JsonSchema;
-    nullableString(description: string, options?: Omit<JsonSchemaOptions, "description">): JsonSchema;
+    nullableString(description: string, options?: Omit<StringOptions, "description">): JsonSchema;
     nullableInteger(description: string, options?: Omit<NumberOptions, "description">): JsonSchema;
     nullableNumber(description: string, options?: Omit<NumberOptions, "description">): JsonSchema;
     nullableBoolean(description: string, options?: Omit<JsonSchemaOptions, "description">): JsonSchema;
@@ -56,13 +64,13 @@ export declare const jsonSchema: {
     date(description: string, options?: Omit<StringOptions, "description" | "format">): JsonSchema;
     uuid(description: string): JsonSchema;
     stringPattern(pattern: string, options?: JsonSchemaOptions): JsonSchema;
-    stringEnum(valuesOrDescription: readonly string[] | string, optionsOrValues?: JsonSchemaOptions | readonly string[]): JsonSchema;
+    stringEnum(valuesOrDescription: readonly string[] | string, optionsOrValues?: JsonSchemaOptions | readonly string[], maybeOptions?: JsonSchemaOptions): JsonSchema;
     integer(optionsOrDescription?: NumberOptions | string, maybeOptions?: Omit<NumberOptions, "description">): JsonSchema;
     positiveInteger(description: string, options?: Omit<NumberOptions, "description" | "minimum">): JsonSchema;
     nonNegativeInteger(description: string, options?: Omit<NumberOptions, "description" | "minimum">): JsonSchema;
     number(optionsOrDescription?: NumberOptions | string, maybeOptions?: Omit<NumberOptions, "description">): JsonSchema;
     boolean(optionsOrDescription?: JsonSchemaOptions | string): JsonSchema;
-    literal(value: string | number | boolean, options?: JsonSchemaOptions): JsonSchema;
+    literal(value: string | number | boolean | null, options?: JsonSchemaOptions): JsonSchema;
     optional(schema: JsonSchema): JsonSchema;
     describe(schema: JsonSchema, description: string): JsonSchema;
     withDefault(schema: JsonSchema, defaultValue: unknown): JsonSchema;

package/src/core/json-schema.js

@@ -28,6 +28,10 @@ export const jsonSchema = {
             schema.required = required;
         if (options.defs)
             schema.$defs = options.defs;
+        for (const key of ["minProperties", "maxProperties", "propertyNames", "allOf", "anyOf", "oneOf"]) {
+            if (options[key] !== undefined)
+                schema[key] = options[key];
+        }
         return withOptions(schema, options);
     },
     requiredObject(description, properties) {
@@ -110,10 +114,10 @@ export const jsonSchema = {
     stringPattern(pattern, options = {}) {
         return withOptions({ type: "string", pattern }, options);
     },
-    stringEnum(valuesOrDescription, optionsOrValues = {}) {
+    stringEnum(valuesOrDescription, optionsOrValues = {}, maybeOptions = {}) {
         const values = typeof valuesOrDescription === "string" ? optionsOrValues : valuesOrDescription;
         const options = typeof valuesOrDescription === "string"
-            ? { description: valuesOrDescription }
+            ? { ...maybeOptions, description: valuesOrDescription }
             : optionsOrValues;
         return withOptions({ type: "string", enum: values }, options);
     },
@@ -128,6 +132,8 @@ export const jsonSchema = {
             schema.maximum = options.maximum;
         if (options.exclusiveMinimum != null)
             schema.exclusiveMinimum = options.exclusiveMinimum;
+        if (options.multipleOf != null)
+            schema.multipleOf = options.multipleOf;
         return withOptions(schema, options);
     },
     positiveInteger(description, options = {}) {
@@ -147,6 +153,8 @@ export const jsonSchema = {
             schema.maximum = options.maximum;
         if (options.exclusiveMinimum != null)
             schema.exclusiveMinimum = options.exclusiveMinimum;
+        if (options.multipleOf != null)
+            schema.multipleOf = options.multipleOf;
         return withOptions(schema, options);
     },
     boolean(optionsOrDescription = {}) {
@@ -154,7 +162,7 @@ export const jsonSchema = {
         return withOptions({ type: "boolean" }, options);
     },
     literal(value, options = {}) {
-        return withOptions({ const: value, type: typeof value }, options);
+        return withOptions({ const: value, type: value === null ? "null" : typeof value }, options);
     },
     optional(schema) {
         const optionalSchema = { ...schema };
@@ -313,5 +321,7 @@ function withOptions(schema, options) {
         schema.default = options.default;
     if (options.format)
         schema.format = options.format;
+    if (options.not !== undefined)
+        schema.not = options.not;
     return schema;
 }

package/src/core/provider-network-policy.d.ts

@@ -0,0 +1,15 @@
+/** Runtime-owned egress permissions; never populate them from provider input. */
+export interface ProviderNetworkPolicy {
+    /**
+     * Runtime permission read by isPrivateNetworkAccessAllowed(). Binding this policy
+     * alone does not relax fetch targets: the provider must also opt in through its
+     * transport's allowPrivateNetwork callback. Reserved targets stay blocked.
+     */
+    readonly allowPrivateNetwork?: boolean;
+    /** Hosts whose DNS answers may use private or VPN-mapped ranges. */
+    readonly trustedHosts?: readonly string[];
+}
+/** The active runtime's policy, or public-only access outside a runtime. */
+export declare function getProviderNetworkPolicy(): ProviderNetworkPolicy;
+/** Bind policy to asynchronous work, including provider callbacks and non-HTTP transports. */
+export declare function withProviderNetworkPolicy<T>(policy: ProviderNetworkPolicy, work: () => T): T;

package/src/core/provider-network-policy.js

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const scopes = new AsyncLocalStorage();
+const publicNetworkPolicy = Object.freeze({});
+/** The active runtime's policy, or public-only access outside a runtime. */
+export function getProviderNetworkPolicy() {
+    return scopes.getStore() ?? publicNetworkPolicy;
+}
+/** Bind policy to asynchronous work, including provider callbacks and non-HTTP transports. */
+export function withProviderNetworkPolicy(policy, work) {
+    return scopes.run(policy, work);
+}

package/src/core/request.d.ts

@@ -65,25 +65,29 @@ export interface PublicHttpUrlOptions {
     /** Allow RFC 1918, shared-address-space, and private hostname targets while retaining reserved-target guards. */
     allowPrivateNetwork?: boolean;
 }
-/** Configure whether opted-in providers may target private networks (called once at deployment bootstrap). */
-export declare function setPrivateNetworkAccessAllowed(allowed: boolean): void;
-/** Whether the current deployment allows opted-in providers to target private networks. */
+/**
+ * Read the active asynchronous runtime context’s private-network permission.
+ * Self-hosted providers opt into this permission through their URL and transport guards.
+ *
+ * Off by default so a shared/multi-tenant runtime keeps a public-only SSRF guard
+ * and a tenant cannot turn a self-hosted connection into an SSRF pivot into the
+ * operator's internal network. Single-tenant, self-hosted operators enable it
+ * through the `OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK` environment variable.
+ *
+ * Even when enabled, reserved, loopback, link-local, cloud-metadata, multicast,
+ * and IPv6 targets remain blocked by {@link assertPublicHttpUrl}.
+ */
 export declare function isPrivateNetworkAccessAllowed(): boolean;
 /** Parse the `OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK` flag; only explicit truthy values enable it. */
 export declare function parsePrivateNetworkAccessFlag(value: string | undefined): boolean;
 /**
- * Configure the hosts that may resolve through private or VPN-mapped ranges
- * (called once at deployment bootstrap).
- */
-export declare function setEgressTrustedHosts(hosts: readonly string[]): void;
-/**
- * Whether `hostname` may resolve through private or VPN-mapped ranges.
+ * Whether the active runtime trusts this hostname's private or VPN-mapped DNS answers.
+ * No hosts are trusted outside a configured runtime context.
  *
- * An entry starting with `.` matches that domain and its subdomains
- * (`.feishu.cn` covers `feishu.cn` and `open.feishu.cn`); any other entry must
- * match the host exactly. Only affects addresses a hostname resolves to — a URL
- * whose host is already a literal private or reserved IP is rejected earlier by
- * {@link assertPublicHttpUrl} and this list does not reach it.
+ * An entry starting with `.` matches the domain and its subdomains; other entries
+ * match exactly. The exception applies only to DNS answers, not literal IP URLs.
+ * It supports corporate VPNs that map public domains into private or benchmark
+ * ranges. Loopback, link-local, cloud-metadata and other unsafe addresses remain blocked.
  */
 export declare function isEgressTrustedHost(hostname: string): boolean;
 /**