@zackbart/connecta 0.28.1 → 0.29.0

package/dist/operator-record.js

@@ -0,0 +1,420 @@
+// What an operator may read about a failure: log records and status text.
+// Web-API only — no node: imports here.
+//
+// Inbound identity-provider text never enters operator logs or status, even
+// when it fits a grammar. Activity retains its separate typed actor fields.
+//
+// Threat model. INV-6 here covers records of calls and failures: logs,
+// activity rows, status and statusFor, health, doctor output, and any native
+// runtime output connecta triggers (workerd's console). Text a downstream
+// server, HTTP API, or client authored, and anything derived from it, never
+// reaches one as arbitrary text. Self-declared client name/version facts in
+// activity use the bounded ASCII grammars in activityClientFact; invalid values are
+// absent at recording, SQL write/read, and operator UI boundaries. Client
+// capabilities and other metadata are never recorded. Every typed field
+// connecta records is checked against a closed set or a grammar. Operator-
+// authored code (custom connectors, plugin `status()`, decorators) is trusted
+// to follow the contract, and connecta still checks
+// the typed fields it records from it; deliberately adversarial operator code
+// is out of scope.
+//
+// Catalog metadata a connector serves is configuration the operator chose to
+// load, and agents already see it: a tool name that fits MCP's tool-name
+// grammar, a description, and input and output schemas may appear in the
+// authenticated operator page's catalog views, and such a name may be
+// logged. A name outside the grammar is withheld everywhere operator-facing,
+// the page included. Names containing C0, DEL, or C1 are dropped at catalog
+// intake; spaces and non-ASCII names remain callable with withheld records.
+//
+// INV-6 says logs carry no arguments, results, code, or raw downstream error
+// text. Filtering errors where they arise kept missing sources: a validator's
+// diagnostic, a stream's TypeError, a JSON-RPC error the agent may see. So the
+// rule is enforced here, at the sink. A failure reaches an operator only as
+// the fields of a `FailureRecord`, which `failureRecord` alone builds: each
+// one copied from an explicit list, checked against a constant table or a
+// grammar, and never taken from an error's message, cause, stack, data,
+// nested errors, or name. `logFailure` writes nothing else, and every status
+// message about a failure comes from `describeFailure`
+// (test/operator-record-sources.node.test.ts holds src/ to that).
+//
+// Provenance is by identity, never by shape. Text that merely looks like
+// connecta's (an error named like one of its classes, a status sentence
+// shaped like a record) carries no weight: a class label comes from the
+// prototype chain, a status message from the status object connecta built.
+//
+// Agent-facing results are a different surface with a different rule: a
+// downstream's own answer to a call may reach the agent that made it (see
+// documentation/architecture.md, "Errors and records"). Core's sent-secrets
+// boundary removes credentials used by the upstream request from those answers, including
+// allowed diagnostics, tool results and nested error causes/data (INV-5).
+import { classificationCode, ConnectorCallError, NETWORK_ERROR_CODES, WithheldTextError, } from "./errors.js";
+const STEPS = new Set([
+    "MCP handshake",
+    "tools/list",
+    "tools/call",
+    "resources/read",
+    "OAuth discovery",
+    "OAuth client registration",
+    "OAuth token request",
+    "OAuth flow",
+    "handler",
+]);
+/**
+ * Registered OAuth `error` codes: the pinned SDK's `OAuthErrorCode` values
+ * (RFC 6749, 6750, 7591, 8707, 9449) and RFC 7591's software-statement pair.
+ */
+export const OAUTH_ERROR_CODES = new Set([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    "access_denied",
+    "server_error",
+    "temporarily_unavailable",
+    "unsupported_response_type",
+    "unsupported_token_type",
+    "invalid_token",
+    "method_not_allowed",
+    "too_many_requests",
+    "invalid_client_metadata",
+    "invalid_redirect_uri",
+    "insufficient_scope",
+    "invalid_target",
+    "invalid_dpop_proof",
+    "use_dpop_nonce",
+    "invalid_software_statement",
+    "unapproved_software_statement",
+]);
+const SOURCES = new Set([
+    "call_tool",
+    "call_destructive_tool",
+    "batch_call",
+    "execute_code",
+    "resume_execution",
+]);
+const MODES = new Set(["continue", "restart"]);
+const STATUS_STATES = new Set(["ok", "auth_required", "credential_required", "error"]);
+/** A status state, or `failed` for a status that could not be read at all. */
+const STATES = new Set([...STATUS_STATES, "failed"]);
+const AUTH_DENIAL_REASONS = new Set([
+    "authentication_failed",
+    "authorization_header_invalid",
+    "token_type_mismatch",
+    "oauth_verification_failed",
+    "oauth_client_not_allowed",
+    "oauth_binding_mismatch",
+    "session_origin_mismatch",
+    "user_missing",
+    "email_lookup_failed",
+    "verified_email_invalid",
+    "email_domain_denied",
+    "gate_denied",
+    "gate_failed",
+    "pool_not_declared",
+    "pool_grant_denied",
+    "pool_grant_threw",
+]);
+/** The registry's connector id grammar (src/registry.ts). */
+const CONNECTOR_ID_RE = /^[a-z0-9_-]{1,64}$/;
+/** MCP's tool name grammar (SEP-986). */
+const TOOL_NAME_RE = /^[A-Za-z0-9_.-]{1,128}$/;
+const LABEL_RE = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
+/** What stands in for a name connecta could not vouch for. */
+const UNLISTED_TOOL = "<unlisted>";
+/**
+ * A catalog entry whose name breaks MCP's tool-name grammar. MCP does not
+ * require that grammar and real servers ship spaced or non-ASCII names, so
+ * the catalog keeps such a tool callable (src/connector-access.ts); only its
+ * name stays out of records.
+ */
+const WITHHELD_TOOL = "<withheld>";
+const UNKNOWN_CONNECTOR = "<unknown>";
+// ---------------------------------------------------------------------------
+// Error class labels, by identity
+/** Prototype → label. Labels are literals in source, never read from an error. */
+const labels = new Map();
+const labelNames = new Set(["DOMException", "AbortError", "TimeoutError"]);
+/**
+ * Name `ctor`'s instances `label` in records and fixed text. Call once, at
+ * module scope, beside the class. An error whose prototype chain reaches no
+ * labelled class has no label; its `name` is never consulted.
+ */
+export function labelErrorClass(ctor, label) {
+    if (!LABEL_RE.test(label))
+        throw new TypeError(`Invalid error class label "${label}"`);
+    labels.set(ctor.prototype, label);
+    labelNames.add(label);
+}
+for (const [ctor, label] of [
+    [Error, "Error"],
+    [TypeError, "TypeError"],
+    [RangeError, "RangeError"],
+    [SyntaxError, "SyntaxError"],
+    [ReferenceError, "ReferenceError"],
+    [URIError, "URIError"],
+    [EvalError, "EvalError"],
+    [AggregateError, "AggregateError"],
+    [ConnectorCallError, "ConnectorCallError"],
+    [WithheldTextError, "WithheldTextError"],
+]) {
+    labelErrorClass(ctor, label);
+}
+/** The two DOMException names a record tells apart; any other is `DOMException`. */
+const DOM_EXCEPTION_LABELS = new Set(["AbortError", "TimeoutError"]);
+/**
+ * The label of the nearest labelled class on `failure`'s prototype chain.
+ * A genuine DOMException is told as `AbortError` or `TimeoutError` when its
+ * name is exactly one of those, else `DOMException`.
+ */
+export function errorLabel(failure) {
+    if (failure === null || typeof failure !== "object")
+        return undefined;
+    try {
+        for (let proto = Object.getPrototypeOf(failure); proto !== null; proto = Object.getPrototypeOf(proto)) {
+            if (typeof DOMException === "function" && proto === DOMException.prototype) {
+                const name = failure.name;
+                return DOM_EXCEPTION_LABELS.has(name) ? name : "DOMException";
+            }
+            const label = labels.get(proto);
+            if (label)
+                return label;
+        }
+    }
+    catch {
+        // A proxy, or a DOMException-shaped object without its internal slot.
+    }
+    return undefined;
+}
+function origin(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.origin.length <= 253 ? url.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function httpStatus(value) {
+    return Number.isInteger(value) && value >= 100 && value <= 599
+        ? value
+        : undefined;
+}
+function member(value, table) {
+    return typeof value === "string" && table.has(value) ? value : undefined;
+}
+function checkedFacts(facts) {
+    if (!facts)
+        return {};
+    return {
+        ...defined("step", member(facts.step, STEPS)),
+        ...defined("origin", origin(facts.origin)),
+        ...defined("httpStatus", httpStatus(facts.httpStatus)),
+        ...defined("oauthError", member(facts.oauthError, OAUTH_ERROR_CODES)),
+        ...defined("errorClass", member(facts.errorClass, labelNames)),
+    };
+}
+function defined(key, value) {
+    return (value === undefined ? {} : { [key]: value });
+}
+/**
+ * Facts attached to failures by identity, never as properties: nothing about
+ * the failure's own shape changes, and nothing a caller can see grows.
+ */
+const attached = new WeakMap();
+/** Note what connecta knows about `failure` for any record made of it later. */
+export function attachFailureFacts(failure, facts) {
+    if (failure !== null && typeof failure === "object") {
+        attached.set(failure, { ...attached.get(failure), ...checkedFacts(facts) });
+    }
+    return failure;
+}
+/** The facts and class label of `from`, kept for `to` (its classified form, say). */
+export function carryFailureFacts(from, to) {
+    if (to === null || typeof to !== "object")
+        return to;
+    const facts = from !== null && typeof from === "object" ? attached.get(from) : undefined;
+    const errorClass = errorLabel(from);
+    // A class carried here already (the original behind a rebuilt error) wins.
+    const carried = { ...(errorClass ? { errorClass } : {}), ...facts };
+    attached.set(to, { ...carried, ...attached.get(to) });
+    return to;
+}
+const built = new WeakSet();
+function count(value, max) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= max
+        ? Math.round(value)
+        : undefined;
+}
+function connectorId(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" && CONNECTOR_ID_RE.test(value) ? value : UNKNOWN_CONNECTOR;
+}
+/**
+ * How an operator record names a catalog entry: its name when it fits MCP's
+ * tool-name grammar, else `<withheld>`. Activity rows and the operator page's
+ * catalog use it too, so a withheld name appears nowhere an operator reads.
+ */
+export function recordedToolName(entry) {
+    return typeof entry.name === "string" && TOOL_NAME_RE.test(entry.name) ? entry.name : WITHHELD_TOOL;
+}
+function checkedSubject(subject) {
+    const tool = subject.tool;
+    return {
+        ...defined("reason", member(subject.reason, AUTH_DENIAL_REASONS)),
+        ...defined("connector", connectorId(subject.connector)),
+        ...("tool" in subject
+            ? { tool: tool === null || typeof tool !== "object" ? UNLISTED_TOOL : recordedToolName(tool) }
+            : {}),
+        ...defined("source", member(subject.source, SOURCES)),
+        ...defined("state", member(subject.state, STATES)),
+        ...defined("mode", member(subject.mode, MODES)),
+        ...defined("attempts", count(subject.attempts, 1_000)),
+        ...defined("durationMs", count(subject.durationMs, 86_400_000)),
+    };
+}
+/**
+ * Classifications connecta computed (`CallErrorDetails` it built), by
+ * identity. A plain object is read as one only when registered here: a thrown
+ * object shaped like a classification is just a thrown object.
+ */
+const classifications = new WeakSet();
+/** Vouch for `details` as a classification connecta itself computed. */
+export function classifiedFailure(details) {
+    classifications.add(details);
+    return details;
+}
+/** The typed classification `failure` carries. */
+function classification(failure) {
+    let typed;
+    if (failure instanceof ConnectorCallError)
+        typed = failure;
+    else if (failure instanceof WithheldTextError) {
+        typed = { retryable: failure.retryable, ...(failure.timeout ? { code: "timeout" } : {}) };
+    }
+    else if (failure !== null && typeof failure === "object" && classifications.has(failure)) {
+        typed = failure;
+    }
+    const details = typed?.details !== null && typeof typed?.details === "object"
+        ? typed.details
+        : undefined;
+    return {
+        ...defined("code", classificationCode(typed?.code)),
+        ...defined("retryable", typeof typed?.retryable === "boolean" ? typed.retryable : undefined),
+        ...defined("origin", origin(details?.host)),
+        ...defined("errno", member(details?.code, NETWORK_ERROR_CODES)),
+    };
+}
+/**
+ * The record of a failure: the subject's listed fields, each checked; the
+ * facts attached to the failure; its class label; and the typed
+ * classification it carries (a `ConnectorCallError`'s code, retryability,
+ * origin, and errno, or those of a `CallErrorDetails` registered with
+ * `classifiedFailure`). Never its
+ * text, and nothing else from `subject`.
+ */
+export function failureRecord(subject, failure) {
+    const facts = failure !== null && typeof failure === "object" ? attached.get(failure) : undefined;
+    const errorClass = errorLabel(failure);
+    const record = Object.freeze({
+        ...checkedSubject(subject),
+        ...classification(failure),
+        ...(errorClass ? { errorClass } : {}),
+        ...checkedFacts(facts),
+    });
+    built.add(record);
+    return record;
+}
+/** What is logged in place of a record `failureRecord` did not build. */
+const REJECTED_RECORD = Object.freeze({ record: "<rejected>" });
+/**
+ * Log one failure as `[connecta] <event>` and its record. A record
+ * `failureRecord` did not build is replaced, whatever its shape, by a fixed
+ * `{ record: "<rejected>" }`. Never throws: it runs on failure paths, and a
+ * logger that throws is contained here.
+ */
+export function logFailure(logger, event, record, level = "warn") {
+    try {
+        logger[level](`[connecta] ${event}`, built.has(record) ? record : REJECTED_RECORD);
+    }
+    catch {
+        // A failing logger cannot add a failure of its own.
+    }
+}
+/**
+ * A failure in connecta's words, from its record alone:
+ * `Connector "<id>" <step> with <origin> failed with HTTP <status> (<class>, <code>, <errno>).`
+ * Used for status messages, and for agent-facing text where the error's own
+ * may not pass.
+ */
+export function describeFailure(connectorId, failure) {
+    const record = failureRecord({ connector: connectorId }, failure);
+    const where = record.step
+        ? ` ${record.step}${record.origin ? ` with ${record.origin}` : ""}`
+        : record.origin
+            ? ` request to ${record.origin}`
+            : "";
+    const status = record.httpStatus ? ` with HTTP ${record.httpStatus}` : "";
+    const oauth = record.oauthError ? ` and OAuth error ${record.oauthError}` : "";
+    const kind = [record.errorClass, record.code, record.errno].filter(Boolean).join(", ");
+    return `Connector "${record.connector}"${where} failed${status}${oauth}${kind ? ` (${kind})` : ""}.`;
+}
+const ownStatuses = new WeakMap();
+function snapshot(status, failure) {
+    return {
+        state: member(status.state, STATUS_STATES) ?? "error",
+        ...(typeof status.message === "string" ? { message: status.message } : {}),
+        ...(["cimd", "dcr", "static"].includes(status.registrationPath ?? "")
+            ? { registrationPath: status.registrationPath }
+            : {}),
+        ...(status.resourceTemplateRefusals
+            ? {
+                resourceTemplateRefusals: [
+                    ...new Set(status.resourceTemplateRefusals.filter((code) => code === "resource_template_ambiguous" || code === "resource_match_budget_exceeded")),
+                ],
+            }
+            : {}),
+        ...(failure === undefined ? {} : { failure }),
+    };
+}
+/** A status whose message connecta wrote, such as an auth_required notice. */
+export function ownStatus(status) {
+    ownStatuses.set(status, snapshot(status));
+    return status;
+}
+/** An error status described from `failure`'s record, remembering the failure. */
+export function failureStatus(connectorId, failure) {
+    const status = { state: "error", message: describeFailure(connectorId, failure) };
+    ownStatuses.set(status, snapshot(status, failure));
+    return status;
+}
+/**
+ * `status` rebuilt from what connecta approved. A status connecta wrote
+ * (`ownStatus`, `failureStatus`) is rebuilt from the snapshot taken then,
+ * whatever has since been assigned to it. Any other status contributes its
+ * typed state alone: a plugin `status()` seam returns its author's text,
+ * which can quote a downstream, and connecta cannot vouch for it whatever it
+ * looks like.
+ */
+export function boundedStatus(status) {
+    const own = status !== null && typeof status === "object" ? ownStatuses.get(status) : undefined;
+    if (own) {
+        const rebuilt = {
+            state: own.state,
+            ...(own.resourceTemplateRefusals ? { resourceTemplateRefusals: [...own.resourceTemplateRefusals] } : {}),
+            ...(own.message === undefined ? {} : { message: own.message }),
+            ...(own.registrationPath === undefined ? {} : { registrationPath: own.registrationPath }),
+        };
+        ownStatuses.set(rebuilt, own);
+        return rebuilt;
+    }
+    return { state: member(status?.state, STATUS_STATES) ?? "error" };
+}
+/** The failure connecta saw behind a status it described, if any. */
+export function statusFailure(status) {
+    return ownStatuses.get(status)?.failure;
+}

package/dist/operator-ui/assets.js

@@ -0,0 +1,31 @@
+import { OPERATOR_UI_ASSETS } from "./generated.js";
+/** Web APIs only: identical bytes and cache semantics on Node and Workers. */
+export function operatorAsset(request, path) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        return new Response(null, { status: 405, headers: { Allow: "GET, HEAD", "Cache-Control": "no-store" } });
+    }
+    const asset = Object.hasOwn(OPERATOR_UI_ASSETS, path) ? OPERATOR_UI_ASSETS[path] : undefined;
+    if (!asset)
+        return new Response(request.method === "HEAD" ? null : "Not Found", {
+            status: 404,
+            headers: { "Cache-Control": "no-store" },
+        });
+    const headers = {
+        "Content-Type": asset.type,
+        "Cache-Control": "public, max-age=31536000, immutable",
+        "X-Content-Type-Options": "nosniff",
+        ETag: `"${path.slice(path.lastIndexOf("/") + 1)}"`,
+    };
+    if (request.headers
+        .get("If-None-Match")
+        ?.split(",")
+        .some((tag) => tag.trim().replace(/^W\//, "") === headers.ETag || tag.trim() === "*")) {
+        return new Response(null, { status: 304, headers });
+    }
+    const body = request.method === "HEAD"
+        ? null
+        : asset.binary
+            ? Uint8Array.from(atob(asset.body), (char) => char.charCodeAt(0))
+            : asset.body;
+    return new Response(body, { headers });
+}

package/dist/operator-ui/contract.d.ts

@@ -0,0 +1,72 @@
+import type { ActivityOutcome } from "../activity.js";
+import type { ConnectaConfigDescription } from "../describe-config.js";
+import type { ConnectorStatus, ConnectorToolDescription } from "../types.js";
+import type { UiProblem } from "./model.js";
+/** The registry's final verdict, independent of the viewer's pool trust. */
+export interface OperatorTool extends ConnectorToolDescription {
+    address: string;
+    classification: "read" | "write";
+}
+export interface OperatorLastCall {
+    at: string;
+    outcome: ActivityOutcome;
+}
+export interface OperatorConnectorOverlay {
+    id: string;
+    status: ConnectorStatus["state"];
+    /** Selected downstream client mechanism, when a client has been selected. */
+    auth?: {
+        registrationPath: NonNullable<ConnectorStatus["registrationPath"]>;
+    };
+    problem?: UiProblem;
+    tools: OperatorTool[];
+    /** Age of the last complete listing. Static or unobserved catalogs have no age. */
+    catalogAgeMs: number | null;
+    /** Latest visible call in the bounded activity window, or null when unknown. */
+    lastCall: OperatorLastCall | null;
+}
+/** Whole connector access, or exact tool grants. Guarded grants still require a live read verdict. */
+export interface OperatorGrant {
+    connectorId: string;
+    tools: "all" | Array<{
+        name: string;
+        requireReadOnly: boolean;
+    }>;
+}
+export interface OperatorPool {
+    name: string;
+    path: string;
+    trust: "trusted" | "read-only";
+    /** Pool access intersected with the caller's grants. */
+    grants: OperatorGrant[];
+}
+export interface OperatorViewer {
+    interactive: boolean;
+    grants: OperatorGrant[];
+    /** Trust of the root /mcp endpoint. */
+    trust: "trusted" | "read-only";
+    pools: OperatorPool[];
+    permissions: {
+        activity: boolean;
+        accessTokenManagement: boolean;
+        connectors: Array<{
+            id: string;
+            use: boolean;
+            manageSharedAuth: boolean;
+            connectPersonal: boolean;
+        }>;
+    };
+}
+export interface OperatorUiContract {
+    schemaVersion: 1;
+    /** describeConfig's allowlisted snapshot, restricted to this caller's view. */
+    config: ConnectaConfigDescription;
+    /** Leaf provenance, built from the same allowlisted snapshot and scoped with it. */
+    configSources?: Record<string, "default" | "config">;
+    live: {
+        connectors: OperatorConnectorOverlay[];
+        /** Last-call lookup scans at most 1,000 recent rows. No payload or actor is returned. */
+        activity: "available" | "unconfigured" | "forbidden" | "unavailable";
+    };
+    you: OperatorViewer;
+}

package/dist/operator-ui/contract.js

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

package/dist/operator-ui/fix-prompts.d.ts

@@ -0,0 +1,18 @@
+import type { UiCredentialProblem, UiProblem } from "./model.js";
+/**
+ * Every failure the Connections page can show, with the prompt its "Copy fix
+ * prompt" button puts on the clipboard.
+ *
+ * The signature is the guarantee. A prompt is looked up by kind and may name
+ * the connector's configured id; there is no argument an error message, a
+ * downstream body, or a credential could travel through, so none can reach a
+ * coding agent's context by way of this page. The notice beside it is fixed
+ * copy too wherever a downstream could have written the failure (see
+ * `refusedNotice` in view.ts); what remains are the page's own sentences and a
+ * credential form's field checks.
+ */
+export type FixPromptKind = UiProblem | UiCredentialProblem | "credential_test_failed" | "oauth_action_failed" | "catalog_drift";
+/** The clipboard text for one failure. Fixed by kind; see `CATALOGUE`. */
+export declare function fixPrompt(kind: FixPromptKind, connectorId?: string): string;
+/** Every kind, so a test can walk the whole catalogue. */
+export declare const FIX_PROMPT_KINDS: FixPromptKind[];