@zackbart/connecta 0.24.4 → 0.26.0

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;
@@ -129,6 +149,11 @@ export interface ConnectorCredentialConfig {
 }
 export interface CredentialTestResult {
     ok: boolean;
+    /**
+     * Detail for the deployment's log. The operator page shows fixed copy for
+     * `ok` and never this text, since a downstream's reply quoted here can
+     * quote the credential it rejected.
+     */
     message?: string;
 }
 export interface ConnectorContext {
@@ -142,7 +167,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;
     /**
@@ -220,12 +245,23 @@ export interface Connector {
     title?: string;
     /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
     kind?: "mcp" | "api";
+    /**
+     * This connector's own default for its tools that are not explicitly
+     * read-only, inside `execute_code`: `"never"` lets a program call them
+     * without pausing for approval. Reserved for connectors connecta ships
+     * whose writes are cheap to undo (the planned artifacts connector, whose
+     * every write is a new immutable version); a deployment's own connectors
+     * leave it unset and exempt through `execute.approval`, which overrides
+     * this either way. Never read from a downstream catalog — a server cannot
+     * exempt its own tools — and never makes a tool read-only anywhere else.
+     */
+    approval?: "never";
     description?: string;
     /**
      * 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 +284,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
@@ -374,6 +410,8 @@ export interface AdmissionSnapshot {
     maxQueueSize: number;
     queueTimeoutMs: number;
     retryAfterMs: number;
+    /** Hard admitted-request lifetime, present only on the /mcp pool. */
+    maxDurationMs?: number;
     active: number;
     queued: number;
     closed: boolean;

package/dist/ui.d.ts

@@ -1,14 +1,31 @@
 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 ApprovalPolicy } from "./tool-safety.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 type OperatorPage = "connections" | "activity" | "artifacts" | "artifact";
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
+/**
+ * The badge a tool earns, from the predicates core enforces with. Computed
+ * here so the page reports the rule rather than restating it. `exempt` is the
+ * config exemption (#566), which `isApprovalExempt` already refuses to grant
+ * a read-only tool.
+ */
+export declare function uiToolSafety(definition: ToolDef, exempt?: boolean): 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;
@@ -26,12 +43,16 @@ export declare function buildUiData(registry: RegistryView, baseUrl: string, ser
     mayManage?: (id: string) => boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
+    approval?: ApprovalPolicy;
 }): Promise<UiData>;
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
-export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage): string;
+export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage, options?: {
+    /** Where the Connections page lives, when this shell is on another origin. */
+    homeUrl?: string;
+}): string;
 /** Mount the connection UI without enabling any storage or activity module. */
 export declare function operatorUi(options?: {
     branding?: ConnectaBranding;

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";
@@ -20,17 +18,57 @@ function stringForInlineScript(value) {
 const OPERATOR_PAGE_LABELS = {
     connections: "Connections",
     activity: "Activity",
+    artifacts: "Artifacts",
+    artifact: "Artifact",
 };
+/** `/artifacts/<id>` and its snapshots, `/artifacts/<id>/v/<version>`. */
+const ARTIFACT_PAGE = /^\/artifacts\/[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?(?:\/v\/\d{1,9})?$/;
 export function operatorPageForPath(path) {
     if (path === "/")
         return "connections";
     if (path === "/activity")
         return "activity";
+    if (path === "/artifacts")
+        return "artifacts";
+    if (ARTIFACT_PAGE.test(path))
+        return "artifact";
     return undefined;
 }
+/** Everything artifact pages own: shells, their API, and the frame. */
+function isArtifactPath(path) {
+    return path === "/artifacts" || path.startsWith("/artifacts/");
+}
 export function operatorPageTitle(page, configuredTitle) {
     return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
 }
+/**
+ * The badge a tool earns, from the predicates core enforces with. Computed
+ * here so the page reports the rule rather than restating it. `exempt` is the
+ * config exemption (#566), which `isApprovalExempt` already refuses to grant
+ * a read-only tool.
+ */
+export function uiToolSafety(definition, exempt = false) {
+    if (isExplicitlyReadOnly(definition))
+        return "runs_in_programs";
+    return exempt ? "exempt" : "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 +86,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
@@ -229,7 +115,7 @@ function jsonForInlineScript(value) {
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
-export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "connections") {
+export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "connections", options = {}) {
     const clerk = uiAuth?.kind === "clerk" ? uiAuth : undefined;
     // The Clerk loader's origin. A value that fails the gate is dropped rather
     // than escaped into the page: the loader tag is simply not emitted, the gate
@@ -327,6 +213,7 @@ ${clerkScript}
 const AUTH = ${jsonForInlineScript(auth)};
 const MCP_URL = ${jsonForInlineScript(mcpUrl)};
 const INITIAL_PAGE = ${jsonForInlineScript(page)};
+const HOME_URL = ${jsonForInlineScript(options.homeUrl ?? "/")};
 const TITLE_SUFFIX = ${jsonForInlineScript(brand.pageTitle)};
 const PRODUCT_NAME = ${stringForInlineScript(brand.productName)};
 const PRODUCT_DESCRIPTION = ${stringForInlineScript(brand.description)};
@@ -335,15 +222,38 @@ ${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.
+            // Artifact pages are the other: they exist only beside the module.
+            const artifacts = context.opts.artifactsModule;
+            const artifactPath = Boolean(artifacts) && isArtifactPath(context.path);
+            if (!artifactPath && !ownsOperatorPath(reservedPaths, context.path))
+                return null;
+            if (artifactPath && !operatorPageForPath(context.path)) {
+                // The pages' JSON API and the sandboxed frame; the module owns both,
+                // and this bundle imports none of it.
+                return (await artifacts?.handle(context)) ??
+                    new Response("Not Found", { status: 404 });
+            }
             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.26.0";

package/dist/version.js

@@ -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 const CONNECTA_VERSION = "0.24.4";
+export const CONNECTA_VERSION = "0.26.0";