@oomol-lab/open-connector 1.7.0 → 1.9.0

package/src/connection-service.js

@@ -1,6 +1,6 @@
 import { normalizeCredentialValues } from "./core/credential-fields.js";
 import { apiKeyCredentialFields } from "./core/provider-setup.js";
-import { providerFetch } from "./providers/provider-runtime.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}$/;
 /**
@@ -10,6 +10,7 @@ const connectionNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
  * run public actions without configuration.
  */
 export class ConnectionService {
+    providerHttpDispatch;
     catalog;
     oauthCredentialRefreshes = new Map();
     oauthCredentials;
@@ -18,6 +19,7 @@ export class ConnectionService {
     logger;
     marketplace;
     constructor(input) {
+        this.providerHttpDispatch = input.providerHttpDispatch;
         this.catalog = input.catalog;
         this.oauthCredentials = input.oauthCredentials;
         this.providerLoader = input.providerLoader;
@@ -30,11 +32,7 @@ export class ConnectionService {
         const configuredByService = new Map();
         for (const connection of configured) {
             const serviceConnections = configuredByService.get(connection.service) ?? [];
-            serviceConnections.push({
-                id: connection.id,
-                connectionName: connection.connectionName,
-                credential: connection.credential,
-            });
+            serviceConnections.push(connection);
             configuredByService.set(connection.service, serviceConnections);
         }
         const preferences = await this.loadProviderPreferences();
@@ -52,7 +50,9 @@ export class ConnectionService {
      */
     summarizeProviderConnections(provider, connections, preferences) {
         if (connections.length > 0) {
-            const stored = connections.map((connection) => this.createConfiguredConnectionSummary(provider, connection.id, connection.connectionName, connection.credential));
+            const stored = connections.map((connection) => connection.source === "saas"
+                ? this.createManagedConnectionSummary(connection)
+                : this.createConfiguredConnectionSummary(provider, connection.id, connection.connectionName, connection.credential));
             const marketplace = this.createMarketplaceConnectionSummary(provider, preferences);
             return marketplace ? [...stored, marketplace] : stored;
         }
@@ -71,7 +71,7 @@ export class ConnectionService {
     async listAuthenticatedServices(services) {
         const configured = await this.store.list();
         const authenticated = new Set(configured
-            .filter((connection) => connection.credential.authType !== "no_auth")
+            .filter((connection) => connection.source === "saas" || connection.credential.authType !== "no_auth")
             .map((connection) => connection.service));
         const preferences = await this.loadProviderPreferences();
         for (const service of this.marketplace?.getSnapshot()?.actionsByService.keys() ?? []) {
@@ -80,32 +80,40 @@ export class ConnectionService {
         }
         return services.filter((service) => authenticated.has(service));
     }
-    async getConnectionSummary(service, connectionName) {
+    async getConnectionSummary(service, connectionName, connectionId) {
         const provider = this.getProvider(service);
-        const name = normalizeConnectionName(connectionName);
-        const stored = await this.store.get(service, name);
-        const marketplace = await this.resolveMarketplaceSummary(provider, connectionName, Boolean(stored));
+        const stored = await this.selectStoredConnection(service, connectionName, connectionId);
+        const name = stored?.connectionName ?? normalizeConnectionName(connectionName);
+        const marketplace = connectionId
+            ? undefined
+            : await this.resolveMarketplaceSummary(provider, connectionName, Boolean(stored));
         if (marketplace)
             return marketplace;
         if (!stored && connectionName && !this.supportsAuth(provider, "no_auth")) {
             throw new ConnectionError("connection_not_found", `${service} connection not found: ${name}.`);
         }
+        if (stored?.source === "saas")
+            return this.createManagedConnectionSummary(stored);
         return stored
             ? this.createConfiguredConnectionSummary(provider, stored.id, name, stored.credential)
             : this.supportsAuth(provider, "no_auth")
                 ? this.createNoAuthConnectionSummary(provider, name)
                 : undefined;
     }
-    async resolveForExecution(service, connectionName) {
+    async resolveForExecution(service, connectionName, connectionId) {
         const provider = this.getProvider(service);
-        const name = normalizeConnectionName(connectionName);
-        const stored = await this.store.get(service, name);
-        const marketplace = await this.resolveMarketplaceSummary(provider, connectionName, Boolean(stored));
+        const stored = await this.selectStoredConnection(service, connectionName, connectionId);
+        const name = stored?.connectionName ?? normalizeConnectionName(connectionName);
+        const marketplace = connectionId
+            ? undefined
+            : await this.resolveMarketplaceSummary(provider, connectionName, Boolean(stored));
         if (marketplace)
-            return { summary: marketplace, marketplace: true, getCredential: async () => undefined };
+            return { kind: "marketplace", summary: marketplace };
         if (!stored && connectionName && !this.supportsAuth(provider, "no_auth")) {
             throw new ConnectionError("connection_not_found", `${service} connection not found: ${name}.`);
         }
+        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);
@@ -117,6 +125,7 @@ export class ConnectionService {
                 ? this.createNoAuthConnectionSummary(provider, name)
                 : undefined;
         return {
+            kind: "local",
             summary,
             getCredential: async (requestedService) => (requestedService === service ? credential : undefined),
         };
@@ -125,6 +134,8 @@ export class ConnectionService {
         const provider = this.getProvider(service);
         const name = normalizeConnectionName(connectionName);
         const stored = await this.store.get(service, name);
+        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)
@@ -202,12 +213,19 @@ export class ConnectionService {
         };
         return this.saveCredential(provider, credential, input);
     }
-    async setOAuthCredential(service, credential, connectionNameInput, signal) {
-        const storedCredential = await this.prepareOAuthCredential(service, credential, signal);
+    async setOAuthCredential(service, credential, connectionNameInput, signal, retirementGeneration) {
         const connectionName = normalizeConnectionName(connectionNameInput);
-        const stored = await this.store.set(service, connectionName, storedCredential);
+        const generation = retirementGeneration ?? (await this.store.getRetirementGeneration(service, connectionName));
+        const storedCredential = await this.prepareOAuthCredential(service, credential, signal);
+        const stored = await this.store.setIfCurrentGeneration(service, connectionName, storedCredential, generation);
+        if (!stored)
+            throw new ConnectionError("connection_retired", "The connection was disconnected during authorization.");
         return this.createStoredConnectionSummary(this.getAvailableProvider(service), stored.id, connectionName, storedCredential);
     }
+    /** Capture the durable disconnect fence before sending the user to the provider. */
+    async getRetirementGeneration(service, connectionName) {
+        return this.store.getRetirementGeneration(service, normalizeConnectionName(connectionName));
+    }
     async prepareOAuthCredential(service, credential, signal) {
         const provider = this.getAvailableProvider(service);
         if (!this.supportsAuth(provider, "oauth2")) {
@@ -220,6 +238,15 @@ export class ConnectionService {
             ...this.mergeCredentialRuntimeData(provider, "oauth2", credential, validation),
         };
     }
+    async selectStoredConnection(service, name, id) {
+        if (!id)
+            return this.store.get(service, normalizeConnectionName(name));
+        const connection = await this.getStoredConnection(id);
+        if (connection.service !== service ||
+            (name !== undefined && connection.connectionName !== normalizeConnectionName(name)))
+            throw new ConnectionError("connection_not_found", "The selected connection does not match this provider or alias.");
+        return connection;
+    }
     async getStoredConnection(id) {
         const connection = (await this.store.list()).find((item) => item.id === id);
         if (!connection)
@@ -233,11 +260,23 @@ export class ConnectionService {
         return this.createManagedConnectionSummary(await this.getStoredConnection(id));
     }
     createManagedConnectionSummary(stored) {
+        if (stored.source === "saas")
+            return {
+                id: stored.id,
+                service: stored.service,
+                connectionName: stored.connectionName,
+                authType: "oauth2",
+                configured: true,
+                virtual: false,
+                default: stored.connectionName === defaultConnectionName,
+                profile: stored.profile,
+                status: stored.status,
+                comment: stored.comment,
+                saas: stored.reference,
+            };
         const credential = stored.credential;
         return {
-            status: credential.authType === "oauth2" && !credential.refreshToken && isOAuthCredentialExpired(credential)
-                ? "reauth_required"
-                : "active",
+            status: "active",
             ...this.createConfiguredConnectionSummary(this.getProvider(stored.service), stored.id, stored.connectionName, credential),
             comment: credential.authType !== "no_auth" && typeof credential.metadata.connectionComment === "string"
                 ? credential.metadata.connectionComment
@@ -246,6 +285,8 @@ export class ConnectionService {
     }
     async saveCredential(provider, credential, input) {
         const expected = input.expectedConnection;
+        if (expected?.source === "saas")
+            throw new ConnectionError("unsupported_auth_type", "Use the original source when reconnecting a SaaS connection.");
         const previousComment = expected?.credential.authType !== "no_auth" ? expected?.credential.metadata.connectionComment : undefined;
         if (input.comment !== undefined || previousComment !== undefined) {
             credential.metadata.connectionComment = input.comment === undefined ? previousComment : input.comment;
@@ -262,14 +303,62 @@ export class ConnectionService {
         }
         return { ...expected, credential };
     }
-    async disconnect(service, connectionNameInput) {
+    async disconnect(service, connectionNameInput, options = {}) {
         const connectionName = normalizeConnectionName(connectionNameInput);
+        // The credential is read before the delete and revoked after it: a delete the store
+        // refuses (a row bound to active Trigger subscriptions) then ends nothing at the provider,
+        // where revoking first would leave a dead grant behind a row that stays.
+        let stored;
+        let readFailed = false;
+        if (options.revoke === true) {
+            try {
+                stored = await this.store.get(service, connectionName);
+            }
+            catch (error) {
+                readFailed = true;
+                this.logger?.warn({ service, connectionName, error: describeError(error) }, "oauth token revocation skipped");
+            }
+        }
         await this.store.delete(service, connectionName);
+        const revoked = options.revoke !== true
+            ? "skipped"
+            : readFailed
+                ? "failed"
+                : await this.revokeDeletedCredential(service, connectionName, stored);
         const provider = this.catalog.providers.find((provider) => provider.service === service);
         if (provider && this.supportsAuth(provider, "no_auth")) {
-            return this.connectWithoutAuth(service, { connectionName });
+            return { ...(await this.connectWithoutAuth(service, { connectionName })), revoked };
+        }
+        return { service, connectionName, configured: false, revoked };
+    }
+    /**
+     * End the grant at the provider once its credential is deleted here, so a
+     * disconnected provider does not keep an app it no longer sees authorized.
+     * Best effort by design: a provider that refuses or cannot be reached is
+     * logged, and the connection the caller asked to remove is gone either way.
+     */
+    async revokeDeletedCredential(service, connectionName, stored) {
+        const refresher = this.oauthCredentials;
+        if (!refresher?.revoke) {
+            return "unsupported";
+        }
+        const logContext = { service, connectionName };
+        if (!stored || stored.source === "saas" || stored.credential.authType !== "oauth2") {
+            return "unsupported";
+        }
+        try {
+            const outcome = await refresher.revoke(service, stored.credential);
+            this.logger?.info({ ...logContext, revoked: outcome }, "oauth token revocation completed");
+            return outcome;
+        }
+        catch (error) {
+            this.logger?.warn({
+                ...logContext,
+                errorCode: error instanceof ConnectionError ? error.code : "oauth_token_revocation_failed",
+                error: describeError(error),
+            }, "oauth token revocation failed");
+            return "failed";
         }
-        return { service, connectionName, configured: false };
     }
     createConfiguredConnectionSummary(provider, id, connectionName, credential) {
         if (credential.authType === "no_auth") {
@@ -288,6 +377,11 @@ export class ConnectionService {
             connectionName,
             authType: credential.authType,
             configured: true,
+            status: credential.authType === "oauth2" &&
+                (credential.metadata.oauthReauthRequired === true ||
+                    (!credential.refreshToken && isOAuthCredentialExpired(credential)))
+                ? "reauth_required"
+                : "active",
             virtual: false,
             default: connectionName === defaultConnectionName,
             profile: credential.profile,
@@ -398,6 +492,9 @@ export class ConnectionService {
     }
     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;
         }
@@ -425,14 +522,30 @@ export class ConnectionService {
     }
     async refreshOAuthCredential(connection, credential, refresher) {
         const { id, revision, service, connectionName } = connection;
-        const nextCredential = await refresher.refresh(service, credential);
+        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;
+        }
         const updated = await this.store.updateCredential({
             id,
             revision,
             service,
             connectionName,
             credential: nextCredential,
-        });
+        }, true);
         if (!updated) {
             throw new ConnectionError("connection_not_found", `${service} connection changed while its OAuth credential was refreshing. Retry the action.`);
         }
@@ -441,7 +554,7 @@ export class ConnectionService {
     async runCredentialValidator(service, validate, signal) {
         this.assertNotCancelled(signal);
         try {
-            const result = (await validate()) ?? {};
+            const result = (await withProviderHttpDispatchResult({ operation: "credential_validation", service }, validate, this.providerHttpDispatch)) ?? {};
             this.assertNotCancelled(signal);
             return result;
         }
@@ -449,6 +562,8 @@ export class ConnectionService {
             if (signal?.aborted) {
                 throw cancelledConnectionError();
             }
+            if (error instanceof ProviderDispatchRequestError)
+                throw error;
             throw new ConnectionError("credential_verification_failed", error instanceof Error ? error.message : `${service} credential verification failed.`);
         }
     }
@@ -460,7 +575,12 @@ export class ConnectionService {
     buildCredentialRuntimeData(provider, authType, credentialFields, credentialValues, validation) {
         return {
             profile: this.createCredentialProfile(provider, authType, credentialFields, credentialValues, validation),
-            metadata: validation.metadata ?? {},
+            metadata: {
+                ...validation.metadata,
+                providerAccountVerified: Boolean(validation.profile?.accountId ??
+                    readLegacyString(validation.metadata, "providerAccountId") ??
+                    readLegacyString(validation.metadata, "accountId")),
+            },
         };
     }
     mergeCredentialRuntimeData(provider, authType, credential, validation) {
@@ -474,6 +594,9 @@ export class ConnectionService {
                 ...(validation.metadata ?? {}),
                 // Provider validation cannot replace or invent completed consent provenance.
                 oauthAuthorizationId: credential.metadata.oauthAuthorizationId,
+                providerAccountVerified: Boolean(validation.profile?.accountId ??
+                    readLegacyString(validation.metadata, "providerAccountId") ??
+                    readLegacyString(validation.metadata, "accountId")) || credential.metadata.providerAccountVerified === true,
             },
         };
     }
@@ -553,6 +676,9 @@ export class ConnectionError extends Error {
         this.code = code;
     }
 }
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function cancelledConnectionError() {
     return new ConnectionError("connection_cancelled", "Credential validation was cancelled.");
 }

package/src/core/action-policy.d.ts

@@ -1,6 +1,6 @@
 import type { ActionDefinition } from "./types.ts";
 export type PolicySource = "deployment" | "runtime" | "token";
-export type PolicyErrorCode = "action_not_allowed" | "action_blocked" | "proxy_not_allowed" | "proxy_blocked" | "connection_not_allowed";
+export type PolicyErrorCode = "action_not_allowed" | "action_blocked" | "proxy_not_allowed" | "proxy_blocked" | "connection_not_allowed" | "trigger_not_allowed" | "trigger_blocked";
 export interface PolicyCheck {
     source: PolicySource;
     outcome: "allow_match" | "block_match" | "allow_miss";
@@ -20,12 +20,15 @@ export interface PolicyRules {
     blockedActions: string[];
     allowedProxies: string[];
     blockedProxies: string[];
+    allowedTriggers?: string[];
+    blockedTriggers?: string[];
 }
 export interface TokenPolicy {
     allowedActions: string[];
     blockedActions: string[];
     allowedProxies: string[];
     allowedConnections?: string[];
+    allowedTriggers?: string[];
 }
 export interface RuntimePolicyState {
     deployment: PolicyRules;
@@ -37,6 +40,8 @@ export interface ActionPolicyConfig {
     blockedActions?: string[];
     allowedProxies?: string[];
     blockedProxies?: string[];
+    allowedTriggers?: string[];
+    blockedTriggers?: string[];
 }
 /**
  * Immutable policy view shared by every policy consumer in one request.
@@ -46,10 +51,12 @@ export declare class ActionPolicySnapshot {
     private readonly layers;
     private readonly proxyLayers;
     private readonly tokenProxyRules?;
+    private readonly tokenTriggerRules?;
     private readonly allowedConnections;
     constructor(deployment: PolicyRules, runtime: PolicyRules, token?: TokenPolicy, updatedAt?: string);
     evaluate(action: ActionDefinition): ActionPolicyDecision;
     evaluateProxy(service: string): ActionPolicyDecision;
+    evaluateTrigger(id: string): ActionPolicyDecision;
     evaluateConnection(connectionId?: string): ActionPolicyDecision;
 }
 /**

package/src/core/action-policy.js

@@ -6,6 +6,7 @@ export class ActionPolicySnapshot {
     layers;
     proxyLayers;
     tokenProxyRules;
+    tokenTriggerRules;
     allowedConnections;
     constructor(deployment, runtime, token, updatedAt) {
         const deploymentRules = immutablePolicyRules(deployment);
@@ -24,6 +25,7 @@ export class ActionPolicySnapshot {
             const tokenLayer = compileLayer("token", tokenRules);
             this.layers.push(tokenLayer);
             this.tokenProxyRules = tokenLayer.allowedProxies;
+            this.tokenTriggerRules = (token.allowedTriggers ?? []).map(compileActionRule);
         }
     }
     evaluate(action) {
@@ -98,6 +100,45 @@ export class ActionPolicySnapshot {
         }
         return { allowed: true, checks };
     }
+    evaluateTrigger(id) {
+        const checks = [];
+        for (const layer of this.proxyLayers) {
+            const blocked = layer.blockedTriggers.find((rule) => rule.matches(id));
+            if (blocked)
+                return {
+                    allowed: false,
+                    code: "trigger_blocked",
+                    message: `${id} is blocked by the Trigger policy.`,
+                    checks: [{ source: layer.source, outcome: "block_match", rule: blocked.pattern }],
+                };
+        }
+        for (const layer of this.proxyLayers) {
+            const allowed = layer.allowedTriggers;
+            if (allowed.length === 0)
+                continue;
+            const match = allowed.find((rule) => rule.matches(id));
+            if (!match)
+                return {
+                    allowed: false,
+                    code: "trigger_not_allowed",
+                    message: `${id} is not included in the Trigger allowlist.`,
+                    checks: [...checks, { source: layer.source, outcome: "allow_miss" }],
+                };
+            checks.push({ source: layer.source, outcome: "allow_match", rule: match.pattern });
+        }
+        if (this.tokenTriggerRules) {
+            const match = this.tokenTriggerRules.find((rule) => rule.matches(id));
+            if (!match)
+                return {
+                    allowed: false,
+                    code: "trigger_not_allowed",
+                    message: `${id} is not granted to this runtime token.`,
+                    checks: [...checks, { source: "token", outcome: "allow_miss" }],
+                };
+            checks.push({ source: "token", outcome: "allow_match", rule: match.pattern });
+        }
+        return { allowed: true, checks };
+    }
     evaluateConnection(connectionId) {
         if (this.allowedConnections.length === 0) {
             return { allowed: true, checks: [] };
@@ -136,6 +177,8 @@ export function emptyPolicyRules() {
         blockedActions: [],
         allowedProxies: [],
         blockedProxies: [],
+        allowedTriggers: [],
+        blockedTriggers: [],
     };
 }
 export function parseActionPolicyList(value) {
@@ -150,6 +193,8 @@ function policyRules(config) {
         blockedActions: config.blockedActions ?? [],
         allowedProxies: config.allowedProxies ?? [],
         blockedProxies: config.blockedProxies ?? [],
+        allowedTriggers: config.allowedTriggers ?? [],
+        blockedTriggers: config.blockedTriggers ?? [],
     });
 }
 function immutablePolicyRules(rules) {
@@ -158,11 +203,15 @@ function immutablePolicyRules(rules) {
         blockedActions: [...rules.blockedActions],
         allowedProxies: [...rules.allowedProxies],
         blockedProxies: [...rules.blockedProxies],
+        allowedTriggers: [...(rules.allowedTriggers ?? [])],
+        blockedTriggers: [...(rules.blockedTriggers ?? [])],
     };
     Object.freeze(immutable.allowedActions);
     Object.freeze(immutable.blockedActions);
     Object.freeze(immutable.allowedProxies);
     Object.freeze(immutable.blockedProxies);
+    Object.freeze(immutable.allowedTriggers);
+    Object.freeze(immutable.blockedTriggers);
     return Object.freeze(immutable);
 }
 function compileLayer(source, rules) {
@@ -172,6 +221,8 @@ function compileLayer(source, rules) {
         blockedActions: rules.blockedActions.map(compileActionRule),
         allowedProxies: rules.allowedProxies.map(compileProxyRule),
         blockedProxies: rules.blockedProxies.map(compileProxyRule),
+        allowedTriggers: (rules.allowedTriggers ?? []).map(compileActionRule),
+        blockedTriggers: (rules.blockedTriggers ?? []).map(compileActionRule),
     };
 }
 function compileActionRule(pattern) {

package/src/core/aws-sigv4.d.ts

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 /**
  * Access key material used by AWS Signature Version 4.
  */
@@ -72,3 +73,5 @@ export declare function buildCanonicalHeaders(headers: Headers): Record<string,
  * SHA-256 hex digest used by SigV4 payload and string-to-sign hashes.
  */
 export declare function sha256Hex(value: string | Uint8Array): string;
+/** Compute the hexadecimal HMAC-SHA256 signature of a UTF-8 message. */
+export declare function hmacHex(key: string | Buffer, value: string): string;

package/src/core/aws-sigv4.js

@@ -175,7 +175,8 @@ function signCanonicalRequest(secretAccessKey, scope, canonicalRequest) {
 function hmacSha256(key, value) {
     return createHmac("sha256", key).update(value).digest();
 }
-function hmacHex(key, value) {
+/** Compute the hexadecimal HMAC-SHA256 signature of a UTF-8 message. */
+export function hmacHex(key, value) {
     return createHmac("sha256", key).update(value).digest("hex");
 }
 function collapseHeaderWhitespace(value) {

package/src/core/cast.d.ts

@@ -100,16 +100,24 @@ export declare function optionalNumber(value: unknown): number | undefined;
 /**
  * Return a finite number from a number or numeric string when present. Examples:
  * `optionalNumberLike("1.5") => 1.5`, `optionalNumberLike("x") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export declare function optionalNumberLike(value: unknown): number | undefined;
 /**
  * Return an integer from a number or numeric string. Examples:
  * `integer("2", "count") => 2`, `integer("x", "count")` throws.
+ *
+ * A blank or whitespace-only string is rejected rather than parsed as zero.
  */
 export declare function integer(value: unknown, fieldName: string, createError?: CastErrorFactory): number;
 /**
  * Return an integer from a number or numeric string when present. Examples:
  * `optionalIntegerLike("2", "count") => 2`, `optionalIntegerLike("", "count") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export declare function optionalIntegerLike(value: unknown, fieldName: string, createError?: CastErrorFactory): number | undefined;
 /**

package/src/core/cast.js

@@ -196,17 +196,22 @@ export function optionalNumber(value) {
 /**
  * Return a finite number from a number or numeric string when present. Examples:
  * `optionalNumberLike("1.5") => 1.5`, `optionalNumberLike("x") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export function optionalNumberLike(value) {
-    const parsed = typeof value === "number" ? value : typeof value === "string" && value !== "" ? Number(value) : Number.NaN;
+    const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
     return Number.isFinite(parsed) ? parsed : undefined;
 }
 /**
  * Return an integer from a number or numeric string. Examples:
  * `integer("2", "count") => 2`, `integer("x", "count")` throws.
+ *
+ * A blank or whitespace-only string is rejected rather than parsed as zero.
  */
 export function integer(value, fieldName, createError = (message) => new CastError(message)) {
-    const parsed = typeof value === "number" ? value : typeof value === "string" && value !== "" ? Number(value) : NaN;
+    const parsed = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
     if (Number.isInteger(parsed)) {
         return parsed;
     }
@@ -215,9 +220,12 @@ export function integer(value, fieldName, createError = (message) => new CastErr
 /**
  * Return an integer from a number or numeric string when present. Examples:
  * `optionalIntegerLike("2", "count") => 2`, `optionalIntegerLike("", "count") => undefined`.
+ *
+ * A blank or whitespace-only string is reported as missing rather than parsed, because
+ * `Number(" ")` is `0` and a blank field would otherwise surface as a real zero.
  */
 export function optionalIntegerLike(value, fieldName, createError = (message) => new CastError(message)) {
-    if (value == null || value === "") {
+    if (value == null || (typeof value === "string" && value.trim() === "")) {
         return undefined;
     }
     return integer(value, fieldName, createError);

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

@@ -1,3 +1,4 @@
+import type { GuardedHttpDispatcher } from "./provider-http-dispatch.ts";
 /**
  * Single resolved address returned by a DNS lookup, mirroring the shape of
  * `node:dns` `lookup(hostname, { all: true })` entries.
@@ -12,6 +13,8 @@ export interface ResolvedAddress {
  */
 export type GuardedFetchDnsLookup = (hostname: string) => Promise<ResolvedAddress[]>;
 export interface GuardedFetchOptions {
+    /** Optional dispatcher at the screened raw-transport seam; every redirect hop passes through it. */
+    dispatchAttempt?: GuardedHttpDispatcher;
     /**
      * Base transport issuing the actual requests. Defaults to the global fetch,
      * resolved per call so test stubs installed later still apply.
@@ -24,8 +27,12 @@ export interface GuardedFetchOptions {
      * load are honored.
      */
     allowPrivateNetwork?: boolean | (() => boolean);
+    /** Whether deployment trusted hosts may bypass private DNS answers. Defaults to true. */
+    allowTrustedHosts?: boolean;
     /** Error factory for guard violations. Defaults to TypeError. */
     createError?: (message: string) => Error;
+    /** Error factory for DNS lookup failures. Defaults to createError. */
+    createResolutionError?: (message: string) => Error;
     /** Maximum redirect hops followed before the request fails. */
     maxRedirects?: number;
     /**
@@ -141,6 +148,7 @@ export declare function unwrapGuardedFetch(fetcher: typeof fetch | undefined): t
  */
 export declare function createGuardedFetch(options?: GuardedFetchOptions): typeof fetch;
 export interface GuardedEgressUrlOptions {
+    allowTrustedHosts?: boolean;
     /** Field name used in guard violation messages, e.g. `"request URL"`. */
     fieldName: string;
     /** Error factory for guard violations. */