@zackbart/connecta 0.28.1 → 0.29.0

package/dist/describe-config.js

@@ -0,0 +1,315 @@
+// `Connecta.describeConfig()`: a secret-free snapshot of what a deployment
+// runs with, built once at construction for the operator UI and
+// `connecta doctor --config`.
+//
+// It is an allowlist serializer. Every value is copied field by field from a
+// known type, and nothing is spread: a config object, a module, a connector,
+// or a connector's own `describe()` result can carry a secret beside the
+// fields named here, and spreading it would publish that secret the day
+// someone adds one. Functions become "custom"/"default" or a boolean and are
+// never called or stringified; every URL, absolute or root-relative, passes
+// through one sanitizer in src/described.ts and keeps origin and path at most;
+// headers keep their names. test/describe-config.test.ts plants a sentinel secret in every
+// secret-bearing position and asserts none survives.
+import { resolveBranding } from "./branding.js";
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
+import { describedEndpoint, describedHref, describedOrigin, describedTools, describedUrl } from "./described.js";
+import { connectorGuideRequired, connectorGuideSummary } from "./skills.js";
+import { CONNECTA_VERSION } from "./version.js";
+const str = (value) => (typeof value === "string" ? value : undefined);
+const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+/** Copy only the named keys whose values are strings or numbers. */
+function pick(value, keys, read) {
+    const out = {};
+    if (typeof value !== "object" || value === null)
+        return out;
+    for (const key of keys) {
+        const item = read(value[key]);
+        if (item !== undefined)
+            out[key] = item;
+    }
+    return out;
+}
+function ownValue(value, key) {
+    return typeof value === "object" && value !== null && Object.hasOwn(value, key)
+        ? value[key]
+        : undefined;
+}
+/** Each resolved value, with "config" where the deployment set it explicitly. */
+function limitGroup(resolved, raw, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = resolved[key];
+        out[key] = {
+            value: typeof value === "number" || typeof value === "boolean" ? value : null,
+            source: ownValue(raw, key) !== undefined ? "config" : "default",
+        };
+    }
+    return out;
+}
+/** An endpoint from a string or an `{ origin, path }` pair, re-parsed so only origin and path survive. */
+function endpointOf(value) {
+    if (typeof value === "object" && value !== null && !(value instanceof URL)) {
+        const { origin, path } = value;
+        return typeof origin === "string"
+            ? describedEndpoint(`${origin}${typeof path === "string" ? path : ""}`)
+            : undefined;
+    }
+    return describedEndpoint(value);
+}
+const AUTH_MODES = new Set(["none", "headers", "credential", "oauth", "request"]);
+const SOURCE_KINDS = new Set(["remote-mcp", "api", "custom"]);
+/** Re-validate a connector's own description: a custom describe() may return anything. */
+function copyAuth(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const auth = value;
+    if (typeof auth.mode !== "string" || !AUTH_MODES.has(auth.mode))
+        return undefined;
+    const names = (item) => Array.isArray(item) ? item.filter((name) => typeof name === "string") : undefined;
+    const authorizationEndpoint = endpointOf(auth.authorizationEndpoint);
+    const tokenEndpoint = endpointOf(auth.tokenEndpoint);
+    const clientMetadataUrl = describedUrl(auth.clientMetadataUrl);
+    const headerNames = names(auth.headerNames);
+    const apiOrigins = names(auth.apiOrigins)?.flatMap((origin) => describedOrigin(origin) ?? []);
+    const authorizationParamNames = names(auth.authorizationParamNames);
+    const tokenRequestHeaderNames = names(auth.tokenRequestHeaderNames);
+    return {
+        mode: auth.mode,
+        ...(headerNames ? { headerNames } : {}),
+        ...(str(auth.header) !== undefined ? { header: str(auth.header) } : {}),
+        ...(auth.scheme === null || typeof auth.scheme === "string" ? { scheme: auth.scheme } : {}),
+        ...(str(auth.scope) !== undefined ? { scope: str(auth.scope) } : {}),
+        ...(clientMetadataUrl ? { clientMetadataUrl } : {}),
+        ...(authorizationEndpoint ? { authorizationEndpoint } : {}),
+        ...(tokenEndpoint ? { tokenEndpoint } : {}),
+        ...(apiOrigins ? { apiOrigins } : {}),
+        ...(str(auth.tokenEndpointAuthMethod) !== undefined
+            ? { tokenEndpointAuthMethod: str(auth.tokenEndpointAuthMethod) }
+            : {}),
+        ...(typeof auth.confidentialClient === "boolean" ? { confidentialClient: auth.confidentialClient } : {}),
+        ...(typeof auth.pkce === "boolean" ? { pkce: auth.pkce } : {}),
+        ...(authorizationParamNames ? { authorizationParamNames } : {}),
+        ...(tokenRequestHeaderNames ? { tokenRequestHeaderNames } : {}),
+    };
+}
+function ownDescription(connector) {
+    let described;
+    try {
+        described = typeof connector.describe === "function" ? connector.describe() : undefined;
+    }
+    catch {
+        described = undefined;
+    }
+    const value = (typeof described === "object" && described !== null ? described : {});
+    const source = (typeof value.source === "object" && value.source !== null ? value.source : {});
+    const kind = typeof source.kind === "string" && SOURCE_KINDS.has(source.kind)
+        ? source.kind
+        : "custom";
+    const endpoint = endpointOf(value.endpoint);
+    const auth = copyAuth(value.auth);
+    const transportValue = value.transport;
+    const transport = typeof transportValue === "object" && transportValue !== null
+        ? (() => {
+            const { versionNegotiation, redirects, requireHttps } = transportValue;
+            return {
+                ...(versionNegotiation === "auto" || versionNegotiation === "legacy" ? { versionNegotiation } : {}),
+                ...(redirects === "none" || redirects === "same-origin" ? { redirects } : {}),
+                ...(typeof requireHttps === "boolean" ? { requireHttps } : {}),
+            };
+        })()
+        : undefined;
+    return {
+        source: { kind, ...(str(source.provider) !== undefined ? { provider: str(source.provider) } : {}) },
+        ...(endpoint ? { endpoint } : {}),
+        ...(auth ? { auth } : {}),
+        ...(transport ? { transport } : {}),
+    };
+}
+function describeConnector(connector, deploymentCap, registry) {
+    const own = ownDescription(connector);
+    const credential = connector.credential;
+    const admission = connector.callAdmission;
+    const guideSummary = connectorGuideSummary(connector);
+    const guided = connector.usageGuide !== undefined;
+    return {
+        id: connector.id,
+        ...(str(connector.title) !== undefined ? { title: connector.title } : {}),
+        ...(str(connector.description) !== undefined ? { description: connector.description } : {}),
+        authScope: connector.authScope === "personal" ? "personal" : "shared",
+        ...own,
+        ...(credential && typeof credential === "object"
+            ? {
+                credential: {
+                    label: String(credential.label),
+                    ...(str(credential.description) !== undefined ? { description: credential.description } : {}),
+                    ...(Array.isArray(credential.fields)
+                        ? {
+                            fields: credential.fields.map((field) => ({
+                                name: String(field.name),
+                                label: String(field.label),
+                                ...(str(field.description) !== undefined ? { description: field.description } : {}),
+                            })),
+                        }
+                        : {}),
+                },
+            }
+            : {}),
+        maxResultBytes: num(connector.maxResultBytes) !== undefined
+            ? { value: connector.maxResultBytes, source: "connector" }
+            : { value: deploymentCap, source: "deployment" },
+        ...(admission && Array.isArray(admission.rules)
+            ? {
+                callAdmission: {
+                    ...(num(admission.maxPartitions) !== undefined ? { maxPartitions: admission.maxPartitions } : {}),
+                    rules: admission.rules.map((rule) => ({
+                        ...pick(rule, ["maxConcurrency", "maxQueueSize", "queueTimeoutMs", "retryAfterMs"], num),
+                        ...(rule.budget && num(rule.budget.maxCalls) !== undefined && num(rule.budget.windowMs) !== undefined
+                            ? { budget: { maxCalls: rule.budget.maxCalls, windowMs: rule.budget.windowMs } }
+                            : {}),
+                        partitioned: typeof rule.partitionKey === "function",
+                    })),
+                },
+            }
+            : {}),
+        ...(guided
+            ? {
+                usageGuide: {
+                    ...(guideSummary !== undefined ? { summary: guideSummary } : {}),
+                    required: connectorGuideRequired(connector),
+                },
+            }
+            : {}),
+        ...(connector.staticTools ? { tools: describedTools(registry.describeStaticTools(connector.id) ?? []) } : {}),
+    };
+}
+const IDENTITY_KEYS = [
+    "connectorAccess",
+    "activityAccess",
+    "credentialAdministration",
+    "accessTokenManagement",
+    "personalConnection",
+];
+const STORE_KINDS = new Set(["memory", "d1", "sqlite"]);
+const storeKind = (described) => typeof described?.kind === "string" && STORE_KINDS.has(described.kind)
+    ? described.kind
+    : "custom";
+/** Build the snapshot. Pure: it reads configuration and calls only describe hooks. */
+export function describeConfig(input) {
+    const { raw, config } = input;
+    const brand = resolveBranding(config.ui?.branding);
+    const accessTokens = config.accessTokens?.describe?.();
+    const storage = config.storage;
+    const activityStore = config.activity?.store.describe?.();
+    const D = CONFIG_DEFAULTS;
+    const websiteUrl = describedEndpoint(config.serverInfo.websiteUrl);
+    const publicUrl = describedEndpoint(config.publicUrl);
+    const productUrl = describedUrl(brand.productUrl);
+    const ownerUrl = describedUrl(brand.ownerUrl);
+    const codeLimits = limitGroup(config.admission.code, ownValue(ownValue(raw, "admission"), "code"), Object.keys(D.admission.code));
+    const description = {
+        schemaVersion: 1,
+        connectaVersion: CONNECTA_VERSION,
+        server: {
+            name: config.serverInfo.name,
+            version: config.serverInfo.version,
+            ...(config.serverInfo.title !== undefined ? { title: config.serverInfo.title } : {}),
+            ...(websiteUrl ? { websiteUrl } : {}),
+            icons: config.serverInfo.icons?.length ?? 0,
+        },
+        urls: {
+            ...(publicUrl ? { publicUrl } : {}),
+            mcpPath: "/mcp",
+            allowedOrigins: config.allowedOrigins === undefined
+                ? "default"
+                : config.allowedOrigins === "*"
+                    ? "*"
+                    : config.allowedOrigins.flatMap((origin) => describedOrigin(origin) ?? []),
+        },
+        executor: {
+            ...(input.executorName !== undefined ? { name: input.executorName } : {}),
+            admission: input.executorAdmits ? "executor" : codeLimits,
+        },
+        limits: {
+            discovery: limitGroup(config.discovery, ownValue(raw, "discovery"), Object.keys(D.discovery)),
+            calls: limitGroup(config.calls, ownValue(raw, "calls"), [
+                "defaultTimeoutMs",
+                "maxResultBytes",
+            ]),
+            results: limitGroup(config.results, ownValue(raw, "results"), Object.keys(D.results)),
+            execute: limitGroup(config.execute, ownValue(raw, "execute"), Object.keys(D.execute)),
+            requests: limitGroup(config.admission.requests, ownValue(ownValue(raw, "admission"), "requests"), Object.keys(D.admission.requests)),
+        },
+        trust: config.trust,
+        classification: structuredClone(config.classification ?? {}),
+        auth: config.auth.map((provider) => ({
+            kind: String(provider.kind),
+            interactive: provider.interactiveOperator === true,
+            ...(str(provider.uiAuth?.kind) !== undefined ? { ui: provider.uiAuth.kind } : {}),
+        })),
+        identity: Object.fromEntries(IDENTITY_KEYS.map((key) => [key, typeof config.identity[key] === "function" ? "custom" : "default"])),
+        pools: Object.entries(config.pools ?? {}).map(([name, pool]) => ({
+            trust: pool.trust,
+            name,
+            path: `/mcp/${name}`,
+            tools: pool.tools.map(String),
+            hasGrant: typeof pool.grant === "function",
+        })),
+        modules: {
+            ui: { enabled: config.ui !== undefined },
+            vault: config.vault
+                ? {
+                    enabled: true,
+                    sealsOAuth: typeof config.vault.seal === "function" && typeof config.vault.open === "function",
+                }
+                : { enabled: false },
+            activity: config.activity
+                ? {
+                    enabled: true,
+                    readable: typeof config.activity.store.list === "function",
+                    ...(str(config.activity.deploymentId) !== undefined ? { deploymentId: config.activity.deploymentId } : {}),
+                    store: {
+                        kind: storeKind(activityStore),
+                        ...(num(activityStore?.retentionDays) !== undefined
+                            ? { retentionDays: activityStore.retentionDays }
+                            : {}),
+                    },
+                }
+                : { enabled: false },
+            accessTokens: config.accessTokens
+                ? {
+                    enabled: true,
+                    ...(num(accessTokens?.maxActive) !== undefined ? { maxActive: accessTokens.maxActive } : {}),
+                }
+                : { enabled: false },
+        },
+        storage: {
+            configured: raw.storage !== undefined,
+            kind: storeKind(storage.describe?.()),
+        },
+        branding: {
+            productName: brand.productName,
+            ...(productUrl !== undefined ? { productUrl } : {}),
+            ...(brand.ownerName !== undefined ? { ownerName: brand.ownerName } : {}),
+            ...(ownerUrl !== undefined ? { ownerUrl } : {}),
+            description: brand.description,
+            faviconHref: describedHref(brand.faviconHref) ?? "/favicon.svg",
+            themeColor: brand.themeColor,
+            theme: {
+                ...pick(brand.theme, ["accent", "radius", "fontFamily", "monoFamily"], str),
+                colorScheme: brand.theme.colorScheme,
+            },
+        },
+        deploymentInfo: Object.keys(config.deploymentInfo ?? {}),
+        connectors: config.connectors.map((connector) => describeConnector(connector, config.calls.maxResultBytes, input.registry)),
+    };
+    return deepFreeze(description);
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}

package/dist/described.js

@@ -0,0 +1,106 @@
+// Small, allowlisting builders shared by every `Connector.describe()` and by
+// `describeConfig()` itself. Each one copies named fields of known types and
+// nothing else, so a value that carries a secret — a URL's userinfo or query,
+// a header's value, a function's source — has no path into a description.
+/**
+ * Origin and path of an absolute http(s) URL; undefined for anything else.
+ *
+ * The scheme is allowlisted, not just parsed: `blob:` and other schemes that
+ * wrap a URL report the inner URL's origin while their `pathname` is the
+ * whole inner URL, userinfo included, and `data:` or `javascript:` carry
+ * their payload in the path. Every field a description reports is a web
+ * URL, so any other scheme is omitted rather than reduced.
+ */
+export function describedEndpoint(value) {
+    if (typeof value !== "string" && !(value instanceof URL))
+        return undefined;
+    try {
+        const url = new URL(value);
+        if ((url.protocol !== "https:" && url.protocol !== "http:") || url.origin === "null")
+            return undefined;
+        return { origin: url.origin, path: url.pathname };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * An absolute URL as `origin + path`: userinfo, query, and fragment dropped.
+ * Every URL a description emits as a string goes through this or
+ * {@link describedHref}, so none carries a token a deployment put in it.
+ */
+export function describedUrl(value) {
+    const endpoint = describedEndpoint(value);
+    return endpoint ? `${endpoint.origin}${endpoint.path}` : undefined;
+}
+/** An origin alone, from any absolute URL. */
+export function describedOrigin(value) {
+    return describedEndpoint(value)?.origin;
+}
+/**
+ * An href that may be root-relative (`/favicon.svg?v=…`): an absolute one as
+ * {@link describedUrl}, a relative one as its path alone.
+ */
+export function describedHref(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const absolute = describedUrl(value);
+    if (absolute !== undefined)
+        return absolute;
+    if (!value.startsWith("/") || value.startsWith("//"))
+        return undefined;
+    try {
+        return new URL(value, "https://connecta.invalid").pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+const ANNOTATION_KEYS = {
+    title: "string",
+    readOnlyHint: "boolean",
+    destructiveHint: "boolean",
+    idempotentHint: "boolean",
+    openWorldHint: "boolean",
+};
+function describedAnnotations(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const out = {};
+    for (const [key, type] of Object.entries(ANNOTATION_KEYS)) {
+        const item = value[key];
+        if (typeof item === type)
+            out[key] = item;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * A JSON Schema as plain data. Schemas are declared in source and describe
+ * arguments, never hold them; the round trip drops anything that is not JSON.
+ */
+function describedSchema(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Static tool definitions as `describeConfig()` reports them. */
+export function describedTools(tools) {
+    return tools.map((tool) => {
+        const annotations = describedAnnotations(tool.annotations);
+        const inputSchema = describedSchema(tool.inputSchema);
+        const outputSchema = describedSchema(tool.outputSchema);
+        return {
+            name: String(tool.name),
+            ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+            ...(annotations ? { annotations } : {}),
+            ...(inputSchema ? { inputSchema } : {}),
+            ...(outputSchema ? { outputSchema } : {}),
+            ...(tool.classification ? { classification: tool.classification } : {}),
+        };
+    });
+}

package/dist/downstream-input-context.js

@@ -0,0 +1,119 @@
+import { ConnectorCallError } from "./errors.js";
+import { percentDecoded } from "./credential-url.js";
+export function isDownstreamInputResult(value) {
+    return value !== null && typeof value === "object" && "resultType" in value && value.resultType === "input_required";
+}
+const continuations = new WeakMap();
+const capabilities = new WeakMap();
+export function bindDownstreamCapabilities(scope, declared) {
+    capabilities.set(scope, declared);
+}
+/** Only the relayable declarations travel to the downstream SDK, never grants. */
+export function downstreamInputCapabilities(scope) {
+    return capabilities.get(scope) ?? {};
+}
+export function bindDownstreamContinuation(scope, target) {
+    continuations.set(scope, target);
+}
+export function clearDownstreamContinuation(scope) {
+    continuations.delete(scope);
+}
+export function downstreamWriteContinuation(scope) {
+    return continuations.get(scope)?.write === true;
+}
+/** Check raw output before redaction, paging, caching, or shape observation. */
+export function assertNoPrivateStateEchoes(value, states) {
+    const refused = () => new ConnectorCallError("input_required_invalid", "The downstream response exposes private continuation state.");
+    try {
+        // Literal matching avoids constructing a regex from a 64 KiB opaque value.
+        // There is no credential length floor, and percent hex is case insensitive.
+        const percent = (text) => text.replace(/%[0-9a-f]{2}/gi, (hex) => hex.toUpperCase());
+        const forms = new Set();
+        for (const state of states)
+            if (state)
+                for (const framed of [state, `Bearer ${state}`, `token ${state}`]) {
+                    forms.add(percent(framed));
+                    try {
+                        forms.add(percent(encodeURIComponent(framed)));
+                        forms.add(percent(encodeURI(framed)));
+                    }
+                    catch {
+                        /* Lone surrogates still match literal and JSON-escaped views. */
+                    }
+                    forms.add(percent(new URLSearchParams({ value: framed }).toString().slice(6)));
+                    let binary = "";
+                    for (const byte of new TextEncoder().encode(framed))
+                        binary += String.fromCharCode(byte);
+                    const encoded = btoa(binary);
+                    forms.add(encoded);
+                    forms.add(encoded.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""));
+                }
+        if (!forms.size)
+            return;
+        const escapes = {
+            '"': '"',
+            "\\": "\\",
+            "/": "/",
+            b: "\b",
+            f: "\f",
+            n: "\n",
+            r: "\r",
+            t: "\t",
+        };
+        const matches = (text) => {
+            for (let pass = 0; pass < 3; pass++) {
+                const unescaped = percentDecoded(text);
+                const views = [percent(text), percent(unescaped)];
+                if ([...forms].some((form) => views.some((view) => view.includes(form))))
+                    return true;
+                const decoded = unescaped.replace(/\\(?:u[0-9a-fA-F]{4}|["\\/bfnrt])/g, (escape) => escape[1] === "u" ? String.fromCharCode(parseInt(escape.slice(2), 16)) : escapes[escape[1]]);
+                if (decoded === text)
+                    break;
+                text = decoded;
+            }
+            return false;
+        };
+        const seen = new WeakSet();
+        const visit = (item) => {
+            if (typeof item === "string")
+                return matches(item);
+            if (item === null || typeof item === "boolean" || typeof item === "number")
+                return matches(JSON.stringify(item));
+            if (!item || typeof item !== "object" || seen.has(item))
+                return false;
+            seen.add(item);
+            if (item instanceof Error && matches(item.message))
+                return true;
+            const content = Object.getOwnPropertyDescriptor(item, "content")?.value;
+            if (Array.isArray(content)) {
+                const texts = content
+                    .filter((block) => block?.type === "text" && typeof block.text === "string")
+                    .map((block) => block.text);
+                if (matches(texts.join("")) || matches(texts.join("\n")))
+                    return true;
+            }
+            return Object.entries(Object.getOwnPropertyDescriptors(item)).some(([key, descriptor]) => matches(key) || ("value" in descriptor && visit(descriptor.value)));
+        };
+        if (visit(value))
+            throw refused();
+    }
+    catch {
+        // A privacy-check failure must never expose a matcher diagnostic or state.
+        throw refused();
+    }
+}
+export function assertDownstreamOutputSafe(scope, value) {
+    const continuation = continuations.get(scope);
+    if (continuation)
+        assertNoPrivateStateEchoes(value, continuation.privateStates);
+}
+/** The host binds one verified target before invocation constructs its context. */
+export function downstreamContinuation(scope, connector, address) {
+    const continuation = continuations.get(scope);
+    if (!continuation)
+        return undefined;
+    if (continuation.connector !== connector || continuation.address !== address) {
+        throw new ConnectorCallError("input_required_invalid", "The resolved target no longer matches this continuation.");
+    }
+    return continuation.input;
+}