@zackbart/connecta 0.24.4 → 0.25.0

package/dist/storage/memory.js

@@ -12,27 +12,28 @@ export function memoryStorage() {
         }
         return e;
     };
+    const write = (key, value, ttlSeconds) => {
+        // Rotate through at most 16 existing keys. Live entries cannot keep an
+        // expired tail resident forever, and no request starts a background job.
+        for (let i = 0; i < 16; i++) {
+            const next = sweep.next();
+            if (next.done) {
+                sweep = map.keys();
+                break;
+            }
+            fresh(next.value);
+        }
+        map.set(key, {
+            value,
+            ...(ttlSeconds ? { exp: Date.now() + ttlSeconds * 1000 } : {}),
+        });
+    };
     return {
         async get(key) {
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
-            // Rotate through at most 16 existing keys. Live entries cannot keep an
-            // expired tail resident forever, and no request starts a background job.
-            for (let i = 0; i < 16; i++) {
-                const next = sweep.next();
-                if (next.done) {
-                    sweep = map.keys();
-                    break;
-                }
-                fresh(next.value);
-            }
-            map.set(key, {
-                value,
-                ...(opts?.ttlSeconds
-                    ? { exp: Date.now() + opts.ttlSeconds * 1000 }
-                    : {}),
-            });
+            write(key, value, opts?.ttlSeconds);
         },
         async delete(key) {
             map.delete(key);
@@ -45,5 +46,16 @@ export function memoryStorage() {
             })
                 .sort();
         },
+        // Atomic because nothing between the read and the write yields: the body
+        // runs to completion before any other call on this map can start.
+        async compareAndSet(key, expected, next, opts) {
+            if ((fresh(key)?.value ?? null) !== expected)
+                return false;
+            if (next === null)
+                map.delete(key);
+            else
+                write(key, next, opts?.ttlSeconds);
+            return true;
+        },
     };
 }

package/dist/timeout.js

@@ -1,5 +1,7 @@
 // The deadline vocabulary shared by downstream discovery probes and tool calls.
 // One definition keeps those waits bounded consistently.
+import { Effect } from "effect";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
 /**
  * Generous default bound for a single downstream probe/catalog call. High enough
  * to trip only on a pathological hang, not a realistically slow probe.
@@ -12,54 +14,22 @@ export function normalizeTimeoutMs(value) {
     }
     return Math.max(1, Math.trunc(value));
 }
-/** Resolve after `ms`, or false when the caller aborts first. */
-export function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", cancel);
-            resolve(value);
-        };
-        const timer = setTimeout(() => finish(true), ms);
-        const cancel = () => finish(false);
-        signal?.addEventListener("abort", cancel, { once: true });
-        if (signal?.aborted)
-            cancel();
-    });
-}
+/**
+ * Run one operation under a deadline and the caller's signal, whichever ends
+ * it first.
+ *
+ * The operation gets a signal of its own: the caller's abort is forwarded to
+ * it, and the deadline aborts it with `timeoutError`. Either way the promise
+ * rejects with that signal's reason, without waiting for work that ignores
+ * the signal. A synchronous throw rejects like an asynchronous one. This is
+ * the Promise face of `withDeadlineEffect` (src/runtime/run.ts), which owns
+ * the contract; an Effect caller uses that directly.
+ */
 export function withDeadline(operation, options) {
-    const controller = new AbortController();
-    const forwardAbort = () => controller.abort(options.signal?.reason);
-    options.signal?.addEventListener("abort", forwardAbort, { once: true });
-    if (options.signal?.aborted)
-        forwardAbort();
-    let rejectAbort;
-    const aborted = new Promise((_, reject) => { rejectAbort = reject; });
-    const onAbort = () => rejectAbort(controller.signal.reason ?? options.timeoutError);
-    controller.signal.addEventListener("abort", onAbort, { once: true });
-    if (controller.signal.aborted)
-        onAbort();
-    const timer = options.timeoutMs === undefined
-        ? undefined
-        : setTimeout(() => controller.abort(options.timeoutError), options.timeoutMs);
-    let work;
-    try {
-        work = operation(controller.signal);
-    }
-    catch (error) {
-        work = Promise.reject(error);
-    }
-    return Promise.race([work, aborted]).finally(() => {
-        controller.abort();
-        if (timer)
-            clearTimeout(timer);
-        controller.signal.removeEventListener("abort", onAbort);
-        options.signal?.removeEventListener("abort", forwardAbort);
-    });
+    return runEdge(withDeadlineEffect((signal) => Effect.tryPromise({
+        try: () => operation(signal),
+        catch: (error) => error,
+    }), options));
 }
 /**
  * Give one operation a caller-facing deadline and the matching cancellation

package/dist/types.d.ts

@@ -12,6 +12,26 @@ export interface KVStorage {
      * subsystems that need independent, enumerable records require it explicitly.
      */
     list?(prefix: string): Promise<string[]>;
+    /**
+     * Atomic compare-and-set: write `next` only if the key's current value is
+     * exactly `expected`, and report whether the write happened. `expected:
+     * null` means "absent", and an expired entry is absent. `next: null`
+     * deletes; otherwise `next` is stored with `options.ttlSeconds`, or with no
+     * expiry when that is omitted, exactly as `set` would. On `false` nothing
+     * changed.
+     *
+     * Atomic means linearizable against every other operation on the same
+     * store, `set` and `delete` included: of N concurrent `compareAndSet(key,
+     * null, value)` claims on an absent key, exactly one returns true.
+     *
+     * Optional, because not every backend can promise it: an eventually
+     * consistent store such as Cloudflare Workers KV must omit the method
+     * rather than emulate it with a read followed by a write. Subsystems that
+     * need an atomic claim require it explicitly.
+     */
+    compareAndSet?(key: string, expected: string | null, next: string | null, options?: {
+        ttlSeconds?: number;
+    }): Promise<boolean>;
 }
 export interface Logger {
     debug(...args: unknown[]): void;
@@ -106,7 +126,7 @@ export interface ConnectorCredentialFieldConfig {
     name: string;
     /** Short field label, e.g. "Account email". */
     label: string;
-    /** Plain-language guidance shown in /credentials. Never include the credential itself. */
+    /** Plain-language guidance shown in the connection's credential form in the operator UI. Never include the credential itself. */
     description?: string;
     /** Input placeholder, e.g. "you@example.com". */
     placeholder?: string;
@@ -117,7 +137,7 @@ export interface ConnectorCredentialFieldConfig {
 export interface ConnectorCredentialConfig {
     /** Short group or field label, e.g. "API token" or "Service credentials". */
     label: string;
-    /** Plain-language guidance shown in /credentials. Never include the credential itself. */
+    /** Plain-language guidance shown in the connection's credential form in the operator UI. Never include the credential itself. */
     description?: string;
     /** Password-field placeholder, e.g. "Paste API token". */
     placeholder?: string;
@@ -142,7 +162,7 @@ export interface ConnectorContext {
     /**
      * Read-only access to this connector's human-managed credential. Present
      * only when the connector declares `credential` and the deployment configures
-     * `credentials.encryptionKey`.
+     * `vault`.
      */
     credential?: ConnectorCredentialAccess;
     /**
@@ -225,7 +245,7 @@ export interface Connector {
      * Max inline result size (bytes) for this connector's tools before
      * call_tool truncates and stashes the full text for get_result
      * paging. Overrides `ConnectaConfig.calls.maxResultBytes`;
-     * omit to inherit it (which itself defaults to 50_000). Must be a whole
+     * omit to inherit it (which itself defaults to 24_000). Must be a whole
      * number of bytes >= 1; anything else warns at startup and is ignored, so
      * the connector inherits the deployment-wide cap.
      */
@@ -248,11 +268,11 @@ export interface Connector {
      * configuration; no runtime registration or shared mutable copy exists.
      */
     usageGuide?: string | ConnectorUsageGuide;
-    /** Optional human-managed credential slot rendered on /credentials. */
+    /** Optional human-managed credential slot rendered in the connection in the operator UI. */
     credential?: ConnectorCredentialConfig;
-    /** Optional server-side check used by /credentials' Test action. */
+    /** Optional server-side check used by the connection's Test action in the operator UI. */
     testCredential?(value: string, ctx: ConnectorContext): Promise<CredentialTestResult>;
-    /** Optional multi-field credential check used by /credentials' Test action. */
+    /** Optional multi-field credential check used by the connection's Test action in the operator UI. */
     testCredentials?(values: ConnectorCredentialValues, ctx: ConnectorContext): Promise<CredentialTestResult>;
     /**
      * Statically-known tool defs, exposed by in-code connectors (`api()`) for

package/dist/ui.d.ts

@@ -1,14 +1,28 @@
 import type { OperatorSurface } from "./module-contracts.js";
 import type { CredentialVault } from "./credential-contract.js";
 import { type DeferredWork } from "./connector-scope.js";
-import { type CredentialManagementCapability, type UiData } from "./operator-ui/model.js";
+import { type CredentialManagementCapability, type UiData, type UiProblem, type UiToolSafety } from "./operator-ui/model.js";
 import type { RegistryView } from "./registry.js";
-import type { ConnectaBranding, UiAuthConfig } from "./types.js";
+import type { ConnectaBranding, Connector, ConnectorStatus, ToolDef, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 export type OperatorPage = "connections" | "activity";
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
+/**
+ * The badge a tool earns, from the one predicate core enforces with. Computed
+ * here so the page reports the rule rather than restating it.
+ */
+export declare function uiToolSafety(definition: ToolDef): UiToolSafety;
+/**
+ * The fix-prompt key for a connector that is not usable. Chosen from the
+ * status state and the connector's declared auth shape — configuration, never
+ * the status message, which can carry a downstream error body.
+ */
+export declare function uiProblemFor(connector: Pick<Connector, "credential" | "startAuth">, status: ConnectorStatus["state"], observed: {
+    credentialDrift: boolean;
+    catalogFailed: boolean;
+}): UiProblem | undefined;
 export declare function credentialManagementCapability(input: {
     eligibleOperator: boolean;
     hasCredentialSlots: boolean;

package/dist/ui.js

@@ -1,12 +1,10 @@
 import { routeUi } from "./routes/ui.js";
 import { routeCredentials } from "./routes/credentials.js";
 import { routeOAuthManagement } from "./routes/oauth-management.js";
-import { withDeadline } from "./timeout.js";
-import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape, } from "./credential-rules.js";
-import { closeConnectorScope, } from "./connector-scope.js";
-import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
+import { uiData } from "./routes/ui-data.js";
+import { runEdge } from "./runtime/run.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
-import { CONNECTA_VERSION } from "./version.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
 import { resolveBranding, isSafeHttpsUrl, themeCss } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
@@ -31,6 +29,30 @@ export function operatorPageForPath(path) {
 export function operatorPageTitle(page, configuredTitle) {
     return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
 }
+/**
+ * The badge a tool earns, from the one predicate core enforces with. Computed
+ * here so the page reports the rule rather than restating it.
+ */
+export function uiToolSafety(definition) {
+    return isExplicitlyReadOnly(definition) ? "runs_in_programs" : "needs_approval";
+}
+/**
+ * The fix-prompt key for a connector that is not usable. Chosen from the
+ * status state and the connector's declared auth shape — configuration, never
+ * the status message, which can carry a downstream error body.
+ */
+export function uiProblemFor(connector, status, observed) {
+    if (observed.credentialDrift)
+        return "credential_mismatch";
+    if (status === "error")
+        return "connector_unavailable";
+    if (status === "auth_required") {
+        if (connector.startAuth)
+            return "oauth_required";
+        return connector.credential ? "credential_required" : "auth_required";
+    }
+    return observed.catalogFailed ? "catalog_failed" : undefined;
+}
 export function credentialManagementCapability(input) {
     if (!input.eligibleOperator)
         return "requires_operator";
@@ -48,169 +70,17 @@ export function credentialManagementCapability(input) {
 export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault
     ? "available"
     : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, personalCredentialOwner, detailOptions = {}) {
-    const requestScope = {};
-    const connectorSet = registry.listConnectors();
-    const concurrency = resolveDiscoveryConcurrency(discoveryConcurrency);
-    const settled = await mapSettledWithConcurrency(connectorSet, concurrency, async (c) => {
-        try {
-            return await withDeadline(async (outerSignal) => {
-                const drift = await registry.credentialDriftFor(c.id);
-                outerSignal.throwIfAborted();
-                let tools = [];
-                let status;
-                try {
-                    status = await withDeadline(async (signal) => {
-                        if (drift)
-                            return { state: "auth_required", message: drift };
-                        const current = await registry.statusFor(c.id, baseUrl, requestScope, { signal });
-                        if (current.state === "ok" && !signal.aborted) {
-                            try {
-                                tools = (await registry.getTools(c.id, baseUrl, requestScope, { signal })).map(t => ({ name: t.name, address: `${c.id}.${t.name}`, ...(t.description ? { description: t.description } : {}) }));
-                            }
-                            catch { /* The registry owns the failed catalog observation. */ }
-                        }
-                        return current;
-                    }, { timeoutMs: detailOptions.timeoutMs ?? 30_000, signal: outerSignal, timeoutError: new Error("Connection details timed out. Retry this connection.") });
-                }
-                catch (error) {
-                    status = { state: "error", message: error instanceof Error ? error.message : "Connection details unavailable" };
-                }
-                let credential;
-                const mayManageAuth = detailOptions.mayManage?.(c.id) ?? (c.authScope === "personal" ? Boolean(personalCredentialOwner) : oauthManagement);
-                if (c.credential && credentialVault && mayManageAuth) {
-                    // One rule, shared with the test route: only the hook matching the
-                    // declared credential shape can run, so the button is offered only
-                    // where a click can succeed (src/credentials.ts).
-                    const testRule = credentialTestRule(c);
-                    const credentialFields = (metadata) => c.credential?.fields?.map((field) => {
-                        const fieldMetadata = metadata?.fields?.[field.name];
-                        return {
-                            name: field.name,
-                            label: field.label,
-                            ...(field.description
-                                ? { description: field.description }
-                                : {}),
-                            ...(field.placeholder
-                                ? { placeholder: field.placeholder }
-                                : {}),
-                            inputType: field.inputType ?? "password",
-                            configured: Boolean(fieldMetadata),
-                            ...(fieldMetadata
-                                ? {
-                                    lastFour: fieldMetadata.lastFour,
-                                    updatedAt: fieldMetadata.updatedAt,
-                                }
-                                : {}),
-                        };
-                    });
-                    const credentialCard = {
-                        label: c.credential.label,
-                        ...(c.credential.description
-                            ? { description: c.credential.description }
-                            : {}),
-                        ...(c.credential.placeholder
-                            ? { placeholder: c.credential.placeholder }
-                            : {}),
-                    };
-                    try {
-                        const metadata = await credentialVault.metadata(c.id, c.authScope === "personal" ? personalCredentialOwner : undefined);
-                        const fields = credentialFields(metadata);
-                        const shape = storedCredentialShape(c.credential, metadata?.fields ?? null);
-                        credential = {
-                            ...credentialCard,
-                            ...(fields?.length ? { fields } : {}),
-                            configured: shape.state === "valid",
-                            removable: Boolean(metadata),
-                            ...(metadata
-                                ? {
-                                    lastFour: metadata.lastFour,
-                                    updatedAt: metadata.updatedAt,
-                                }
-                                : {}),
-                            testable: testRule.mode !== null && shape.state !== "mismatch",
-                            ...(shape.state === "mismatch"
-                                ? { error: shape.message }
-                                : {}),
-                            // A dropped field leaves its secret in the vault, and the field
-                            // list below only renders fields the connector still declares —
-                            // so without this line there is nowhere an operator could see it.
-                            ...(shape.state === "valid" && shape.undeclared.length
-                                ? {
-                                    notice: describeUndeclaredCredentialFields(shape.undeclared),
-                                }
-                                : {}),
-                        };
-                    }
-                    catch {
-                        const fields = credentialFields();
-                        credential = {
-                            ...credentialCard,
-                            ...(fields?.length ? { fields } : {}),
-                            configured: false,
-                            removable: true,
-                            testable: testRule.mode !== null,
-                            error: "Stored credential could not be read.",
-                        };
-                    }
-                }
-                outerSignal.throwIfAborted();
-                return {
-                    id: c.id,
-                    authScope: c.authScope ?? "shared",
-                    ...(c.title ? { title: c.title } : {}),
-                    ...(c.description !== undefined
-                        ? { description: c.description }
-                        : {}),
-                    status: status.state,
-                    ...(status.message ? { message: status.message } : {}),
-                    toolCount: tools.length,
-                    tools,
-                    // Counts only, and only when a refresh in this runtime produced them.
-                    // `Registry.statusFor` already rebuilt the report through
-                    // `boundedCatalogDrift`, so what lands here cannot carry a name or a
-                    // schema even if the plugin seam returned one.
-                    ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
-                    ...(status.catalogAccess
-                        ? { catalogAccess: status.catalogAccess }
-                        : {}),
-                    oauth: Boolean(c.startAuth && c.disconnectAuth),
-                    ...(credential ? { credential } : {}),
-                };
-            }, {
-                timeoutMs: detailOptions.timeoutMs ?? 30_000,
-                ...(detailOptions.signal ? { signal: detailOptions.signal } : {}),
-                timeoutError: new Error("Connection details timed out. Retry this connection."),
-            });
-        }
-        catch (error) {
-            return {
-                id: c.id,
-                ...(c.title ? { title: c.title } : {}),
-                authScope: c.authScope ?? "shared",
-                status: "error",
-                oauth: Boolean(c.startAuth && c.disconnectAuth),
-                message: error instanceof Error ? error.message : "Connection details unavailable",
-                toolCount: 0,
-                tools: [],
-            };
-        }
-        finally {
-            await closeConnectorScope(c, registry.contextFor(c.id, baseUrl, requestScope), defer);
-        }
-    });
-    const connectors = settled.map((result) => {
-        if (result.status === "rejected")
-            throw result.reason;
-        return result.value;
-    });
-    return {
+    return runEdge(uiData(registry, baseUrl, {
         serverInfo,
-        connectaVersion: CONNECTA_VERSION,
-        connectors,
+        credentialVault,
         activityEnabled,
         credentialManagement,
-        oauthManagement: oauthManagement || Boolean(personalCredentialOwner),
-    };
+        defer,
+        oauthManagement,
+        discoveryConcurrency,
+        personalCredentialOwner,
+        ...detailOptions,
+    }));
 }
 function escapeHtmlAttr(value) {
     return value
@@ -335,15 +205,29 @@ ${OPERATOR_UI_SCRIPT}</script>
 </body>
 </html>`;
 }
+function ownsOperatorPath(reserved, path) {
+    if (path === "/activity")
+        return true;
+    return reserved.some((pattern) => pattern.endsWith("/*")
+        ? path.startsWith(pattern.slice(0, -1))
+        : path === pattern);
+}
 /** Mount the connection UI without enabling any storage or activity module. */
 export function operatorUi(options = {}) {
+    const reservedPaths = ["/", "/ui", "/ui/*", "/favicon.svg", "/favicon.ico"];
     return {
         ...options,
-        reservedPaths: ["/", "/ui", "/ui/*", "/favicon.svg", "/favicon.ico"],
+        reservedPaths,
         credentialHandoffUrl(baseUrl) {
             return new URL("/", baseUrl).toString();
         },
         async handle(context) {
+            // Everything else belongs to the server, and reaches it untouched: no
+            // route here, and no activity module, runs for a path this surface does
+            // not own. The Activity page is the one addition; the server reserves
+            // it only when history is readable, and routeUi checks the same thing.
+            if (!ownsOperatorPath(reservedPaths, context.path))
+                return null;
             const routes = [
                 ...(context.opts.credentialVault ? [routeCredentials] : []),
                 routeOAuthManagement,

package/dist/url-safety.js

@@ -0,0 +1,157 @@
+/**
+ * Syntactic destination checks for URLs a downstream hands connecta to fetch.
+ *
+ * A remote MCP server's OAuth metadata names further URLs — authorization
+ * servers, token and registration endpoints — that connecta then requests
+ * server-side. Config is the security model: the connector's configured
+ * origin is trusted because an operator wrote it down. Everything else was
+ * learned from the downstream, and a compromised downstream must not be able
+ * to steer connecta at the host's own network (cloud metadata, a LAN admin
+ * panel, a sidecar on loopback).
+ *
+ * The check is by syntax only. The WHATWG URL parser has already folded every
+ * legacy IPv4 spelling (`2130706433`, `0x7f.1`, `0177.0.0.1`) into dotted
+ * decimal and every IPv6 literal into compressed hex, so one canonical form is
+ * all this module reads. It never resolves a name: that needs DNS, which the
+ * Workers-safe core cannot do, and a name that resolves somewhere private — or
+ * rebinds after the check — is out of scope. Pure Web API, no `node:` import.
+ */
+function classifyIpv4(octets) {
+    const [a = 0, b = 0] = octets;
+    if (a === 127)
+        return "loopback";
+    if (a === 0 ||
+        a === 10 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        (a === 100 && b >= 64 && b <= 127)) {
+        return "private";
+    }
+    return "public";
+}
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+const HEXTET = /^[0-9a-f]{1,4}$/;
+function ipv4Octets(host) {
+    const match = IPV4.exec(host);
+    if (!match)
+        return undefined;
+    const octets = match.slice(1).map(Number);
+    return octets.every((octet) => octet <= 255) ? octets : undefined;
+}
+/** Eight 16-bit pieces of a bracketed IPv6 literal, or undefined. */
+function ipv6Pieces(host) {
+    const body = host.slice(1, -1);
+    const halves = body.split("::");
+    if (halves.length > 2)
+        return undefined;
+    const pieces = (part) => {
+        if (!part)
+            return [];
+        const parsed = part.split(":").map((piece) => HEXTET.test(piece) ? Number.parseInt(piece, 16) : Number.NaN);
+        return parsed.some(Number.isNaN) ? undefined : parsed;
+    };
+    const head = pieces(halves[0]);
+    const tail = pieces(halves[1]);
+    if (!head || !tail)
+        return undefined;
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 1 ? missing !== 0 : missing < 0)
+        return undefined;
+    return [...head, ...Array.from({ length: missing }, () => 0), ...tail];
+}
+function classifyIpv6(pieces) {
+    const [first = 0] = pieces;
+    const leadingZeros = pieces.slice(0, 5).every((piece) => piece === 0);
+    if (leadingZeros && pieces[5] === 0 && pieces[6] === 0) {
+        if (pieces[7] === 0)
+            return "private"; // ::
+        if (pieces[7] === 1)
+            return "loopback"; // ::1
+    }
+    // ::ffff:a.b.c.d reaches the mapped IPv4 destination; classify that.
+    if (leadingZeros && pieces[5] === 0xffff) {
+        const high = pieces[6] ?? 0;
+        const low = pieces[7] ?? 0;
+        return classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    }
+    if ((first & 0xfe00) === 0xfc00)
+        return "private"; // fc00::/7
+    if ((first & 0xffc0) === 0xfe80)
+        return "private"; // fe80::/10
+    return "public";
+}
+/**
+ * The hostname the WHATWG parser settles on. Idempotent for a `URL.hostname`;
+ * anything else — a bare IPv6 literal, a legacy IPv4 spelling — is folded the
+ * same way the parser would fold it on the way to a fetch.
+ */
+function canonicalHost(hostname) {
+    if (/[/\\?#@]/.test(hostname))
+        return undefined;
+    const bracketed = hostname.includes(":") && !hostname.startsWith("[")
+        ? `[${hostname}]`
+        : hostname;
+    try {
+        return new URL(`http://${bracketed}/`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Classify a URL host by syntax. A host that does not parse is `private`:
+ * the check fails closed rather than guessing.
+ */
+export function classifyHost(hostname) {
+    const host = canonicalHost(hostname);
+    if (!host)
+        return "private";
+    if (host.startsWith("[")) {
+        const pieces = ipv6Pieces(host);
+        return pieces ? classifyIpv6(pieces) : "private";
+    }
+    const octets = ipv4Octets(host);
+    if (octets)
+        return classifyIpv4(octets);
+    const name = host.endsWith(".") ? host.slice(0, -1) : host;
+    if (name === "localhost" || name.endsWith(".localhost"))
+        return "loopback";
+    return "public";
+}
+/** True for loopback and private hosts alike. */
+export function isPrivateHost(hostname) {
+    return classifyHost(hostname) !== "public";
+}
+/**
+ * Why connecta must not fetch `target`, a URL the downstream advertised, for a
+ * connector configured at `configured` — or undefined when it may.
+ *
+ * - The configured origin is trusted outright: the operator chose it.
+ * - Anything else must be `https` on a host that is not private by syntax.
+ * - A loopback-configured connector (local development) may also learn
+ *   loopback URLs, over `http` too, so a local MCP server with a local
+ *   authorization server keeps working. It still may not learn a LAN or
+ *   link-local address.
+ *
+ * The reason names only the host, never the path, query, or credentials a
+ * learned URL may carry.
+ */
+export function learnedUrlRefusal(configured, target) {
+    if (target.protocol !== "https:" && target.protocol !== "http:") {
+        return `${target.host || "the target"} uses ${target.protocol}, not HTTPS`;
+    }
+    if (target.origin === configured.origin)
+        return undefined;
+    const targetClass = classifyHost(target.hostname);
+    if (targetClass === "loopback" &&
+        classifyHost(configured.hostname) === "loopback") {
+        return undefined;
+    }
+    if (targetClass !== "public") {
+        return `${target.host} is a private, loopback, or link-local address`;
+    }
+    if (target.protocol !== "https:")
+        return `${target.host} is not HTTPS`;
+    return undefined;
+}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.24.4";
+export declare const CONNECTA_VERSION = "0.25.0";