@zackbart/connecta 0.28.1 → 0.30.0

package/dist/module-contracts.d.ts

@@ -1,7 +1,6 @@
-import type { ConnectaBranding, Connector } from "./types.js";
-import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogDriftActivity } from "./activity.js";
+import type { ConnectaBranding } from "./types.js";
+import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogChangeActivity } from "./activity.js";
 import type { RouteContext } from "./routes/shared.js";
-import type { ArtifactRefreshRuntime } from "./artifacts/refresh.js";
 /** Construction-time UI contract. Core never imports the implementation. */
 export interface OperatorSurface {
     readonly branding?: ConnectaBranding;
@@ -16,29 +15,15 @@ export interface ActivityModule {
     readonly readGate?: ActivityReadGate;
     handle(context: RouteContext): Promise<Response | null>;
     readonly recordTool: typeof recordToolActivity;
-    readonly recordDrift: typeof recordCatalogDriftActivity;
-}
-/**
- * The artifacts module, created by `artifacts()` from /artifacts. Core appends
- * its one prebuilt connector to the configured set — the same catalog,
- * invocation, admission, and activity paths as any other — and imports none
- * of its implementation.
- */
-export interface ArtifactsModule {
-    /** The built-in `artifacts` connector. */
-    readonly connector: Connector;
-    /**
-     * Serve the pages' JSON API (`/artifacts/_api/*`) and the sandboxed frame
-     * (`/artifacts/_frame`); null for any other path. The operator UI delegates
-     * here and serves the page shells itself, so without `ui` there are no
-     * artifact routes at all.
-     */
-    handle(context: RouteContext): Promise<Response | null>;
-    /** Bind the optional refresh runner after core has built its registry and executor. */
-    bindRefresh?(runtime: ArtifactRefreshRuntime): void;
+    readonly recordChange: typeof recordCatalogChangeActivity;
 }
 /** Optional client-token authentication and operator lifecycle. */
 export interface AccessTokensModule {
     readonly auth: import("./types.js").InboundAuth;
     handle(context: RouteContext): Promise<Response | null>;
+    /** Token policy for `describeConfig()`; never token material. */
+    describe?(): {
+        maxActive: number;
+        optionSources?: Readonly<Record<string, "default" | "config">>;
+    };
 }

package/dist/node.d.ts

@@ -1,7 +1,5 @@
 import type { Server } from "node:http";
 import type { Connecta } from "./index.js";
-export { fileStorage } from "./storage/file.js";
-export type { FileStorageOptions } from "./storage/file.js";
 export interface ListenOptions {
     port: number;
     /** Interface to bind. Defaults to Node's own (all interfaces). */

package/dist/node.js

@@ -1,7 +1,7 @@
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-export { fileStorage } from "./storage/file.js";
+import { failureRecord, logFailure } from "./operator-record.js";
 /** 10 MiB. Tool arguments are JSON; nothing legitimate approaches this. */
 const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
 const BODY_TOO_LARGE = Symbol("body-too-large");
@@ -113,7 +113,7 @@ export function listen(connecta, portOrOptions) {
                 if (controller.signal.aborted)
                     return;
                 // A headless deployment has nothing else to go on; never swallow this.
-                console.error("[connecta] request failed", error);
+                logFailure(console, "request failed", failureRecord({}, error), "error");
                 if (res.headersSent) {
                     // Mid-stream failure: appending an error string here would corrupt
                     // the partial body the client has already begun reading. Cutting

package/dist/oauth-callback-outcome.js

@@ -107,9 +107,7 @@ export function oauthCallbackOutcome(reason, connector, productName = "Connecta"
         tone: outcome.tone,
         heading: outcome.heading.replace("{name}", () => name),
         message: outcome.message.replace("{product}", () => productName),
-        ...(outcome.fix
-            ? { fixPrompt: renderFixPrompt(outcome.fix, named?.id) }
-            : {}),
+        ...(outcome.fix ? { fixPrompt: renderFixPrompt(outcome.fix, named?.id) } : {}),
     };
 }
 /** A connector's title when it has a usable one, otherwise its id. */

package/dist/oauth-handoff.js

@@ -0,0 +1,194 @@
+import { oauthConnectKeys } from "./storage/keys.js";
+const HANDOFF_TTL_MS = 15 * 60_000;
+const INTERACTIVE_OAUTH_REQUIRED = "An interactive provider (Clerk or Cloudflare Access) is required to connect OAuth connectors.";
+// Length-prefixed fields avoid JSON keys and escaping without reserving any
+// character in an identity. This is an opaque wire encoding, not encryption.
+function encodeHandoff(h) {
+    return [
+        h.connector,
+        h.owner,
+        h.principal,
+        h.origin,
+        h.expiresAt.toString(36),
+        h.nonce,
+        h.force ? "1" : "0",
+        h.after ?? "",
+    ]
+        .map((field) => `${field.length}:${field}`)
+        .join("");
+}
+function decodeHandoff(value) {
+    const fields = [];
+    let offset = 0;
+    while (offset < value.length && fields.length < 8) {
+        const colon = value.indexOf(":", offset);
+        const lengthText = value.slice(offset, colon);
+        if (colon < offset || !/^(0|[1-9][0-9]*)$/.test(lengthText))
+            throw new Error("Invalid handoff field");
+        const length = Number(lengthText);
+        offset = colon + 1;
+        if (!Number.isSafeInteger(length) || length > value.length - offset)
+            throw new Error("Invalid handoff length");
+        fields.push(value.slice(offset, offset + length));
+        offset += length;
+    }
+    const [connector, owner, principal, origin, expiry, nonce, force, after] = fields;
+    if (fields.length !== 8 || offset !== value.length || !/^[0-9a-z]+$/.test(expiry) || !/^[01]$/.test(force))
+        throw new Error("Invalid handoff fields");
+    return {
+        connector: connector,
+        owner: owner,
+        principal: principal,
+        origin: origin,
+        expiresAt: parseInt(expiry, 36),
+        nonce: nonce,
+        force: force === "1",
+        ...(after ? { after } : {}),
+    };
+}
+function encodeSegment(value) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(value))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeSegment(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error("Invalid handoff encoding");
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+    if (encodeSegment(decoded) !== value)
+        throw new Error("Noncanonical handoff encoding");
+    return decoded;
+}
+export function oauthConnectUnavailable(opts) {
+    if (!opts.config.auth.some((provider) => provider.interactiveOperator &&
+        (provider.uiAuth?.kind === "clerk" || provider.uiAuth?.kind === "cloudflare-access"))) {
+        return INTERACTIVE_OAUTH_REQUIRED;
+    }
+    if (!opts.config.vault?.signOAuthHandoff || !opts.config.vault.verifyOAuthHandoff) {
+        return "Connecting OAuth connectors requires a credential vault with a handoff signing key. Configure encryptedCredentialVault(storage, key).";
+    }
+    return undefined;
+}
+export async function oauthConnectUrl(opts, baseUrl, connectorId, principal, force = false, opaque = false) {
+    return (await oauthConnectLink(opts, baseUrl, connectorId, principal, force, opaque)).url;
+}
+export async function oauthConnectLink(opts, baseUrl, connectorId, principal, force = false, opaque = false, after) {
+    const unavailable = oauthConnectUnavailable(opts);
+    if (unavailable)
+        throw new Error(unavailable);
+    const connector = opts.registry.getConnector(connectorId);
+    if (!connector || !principal)
+        throw new Error("OAuth connection requires an initiating user identity.");
+    const handoff = {
+        connector: connectorId,
+        owner: connector.authScope === "personal" ? principal : "shared",
+        principal,
+        origin: new URL(baseUrl).origin,
+        expiresAt: Date.now() + HANDOFF_TTL_MS,
+        nonce: crypto.randomUUID(),
+        force,
+        ...(after ? { after } : {}),
+    };
+    const vault = opts.config.vault;
+    if (opaque && (!vault.seal || !vault.open))
+        throw new Error("URL elicitation requires a sealing credential vault.");
+    const compact = encodeHandoff(handoff);
+    const payload = opaque
+        ? `v4.${encodeSegment(await vault.seal(connectorId, "connecta:connect-link:v4", compact))}`
+        : `v3.${encodeSegment(compact)}`;
+    // Preserve the vault's entire signature and its representation, including
+    // custom vaults, while keeping every URL segment unpadded base64url.
+    const signature = encodeSegment(await vault.signOAuthHandoff(payload));
+    const url = new URL(`/connect/${connectorId}`, baseUrl);
+    url.searchParams.set("h", `${payload}.${signature}`);
+    return { url: url.toString(), nonce: handoff.nonce };
+}
+/** A claim precedes OAuth reset; only a completed start can prove recovery. */
+export async function oauthConnectLinkProgress(opts, baseUrl, id, nonce) {
+    const stage = await opts.registry.contextFor(id, baseUrl).storage.get(oauthConnectKeys.used(nonce));
+    return stage === "used" ? "claimed" : stage === "started" || stage === "failed" ? stage : undefined;
+}
+/** Make outstanding flow links single-use refusals before a completion check. */
+export async function closeOAuthConnectLinks(opts, baseUrl, id, nonces) {
+    const storage = opts.registry.contextFor(id, baseUrl).storage;
+    for (const nonce of nonces) {
+        await storage.compareAndSet(oauthConnectKeys.used(nonce), null, "closed", { ttlSeconds: HANDOFF_TTL_MS / 1000 });
+    }
+}
+/** Consuming a round prevents replay from creating sibling retry lineages. */
+export async function claimAuthRetry(opts, baseUrl, id, nonce) {
+    return opts.registry
+        .contextFor(id, baseUrl)
+        .storage.compareAndSet(oauthConnectKeys.retry(nonce), null, "used", { ttlSeconds: HANDOFF_TTL_MS / 1000 });
+}
+export async function verifyOAuthHandoff(opts, baseUrl, connectorId, token) {
+    if (!token || token.length > 4096)
+        return null;
+    try {
+        const parts = token.split(".");
+        let h;
+        if (parts.length === 3 && (parts[0] === "v3" || parts[0] === "v4")) {
+            const [version, body, signature] = parts;
+            const payload = `${version}.${body}`;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, decodeSegment(signature))))
+                return null;
+            const decoded = decodeSegment(body);
+            h = decodeHandoff(version === "v4" ? await opts.config.vault.open(connectorId, "connecta:connect-link:v4", decoded) : decoded);
+        }
+        else {
+            // Keep pre-upgrade JSON and sealed v2 links until their original expiry.
+            // Authenticate their exact original text; never normalize before verifying.
+            const [payload, signature, ...rest] = parts;
+            if (!payload || !signature || rest.length)
+                return null;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, signature)))
+                return null;
+            h = JSON.parse(payload.startsWith("v2:")
+                ? await opts.config.vault.open(connectorId, "connecta:connect-link:v2", atob(payload.slice(3)))
+                : atob(payload));
+        }
+        const connector = opts.registry.getConnector(connectorId);
+        if (!connector ||
+            h.connector !== connectorId ||
+            typeof h.principal !== "string" ||
+            !h.principal ||
+            h.owner !== (connector.authScope === "personal" ? h.principal : "shared") ||
+            h.origin !== new URL(baseUrl).origin ||
+            !Number.isSafeInteger(h.expiresAt) ||
+            h.expiresAt <= Date.now() ||
+            h.expiresAt > Date.now() + HANDOFF_TTL_MS ||
+            typeof h.nonce !== "string" ||
+            !h.nonce ||
+            typeof h.force !== "boolean")
+            return null;
+        if (h.after !== undefined &&
+            (typeof h.after !== "string" || !/^[a-f0-9-]{36}$/.test(h.after) || h.after === h.nonce || h.force))
+            return null;
+        if (await opts.registry.contextFor(connectorId, baseUrl).storage.get(oauthConnectKeys.used(h.nonce)))
+            return null;
+        return h;
+    }
+    catch {
+        return null;
+    }
+}
+/** Claim only after browser identity and permissions pass, before starting OAuth. */
+export async function consumeOAuthConnectLink(opts, handoff) {
+    if (handoff.expiresAt <= Date.now())
+        return false;
+    const storage = opts.registry.contextFor(handoff.connector, handoff.origin).storage;
+    if (handoff.after && (await storage.get(oauthConnectKeys.used(handoff.after))) !== "started")
+        return false;
+    const expiry = { ttlSeconds: Math.max(1, Math.ceil((handoff.expiresAt - Date.now()) / 1000)) };
+    return storage.compareAndSet(oauthConnectKeys.used(handoff.nonce), null, "used", expiry);
+}
+/** Terminal marker only after the start and every tracked reset have settled. */
+export async function finishOAuthConnectStart(opts, handoff, outcome) {
+    if (handoff.expiresAt <= Date.now())
+        return false;
+    const storage = opts.registry.contextFor(handoff.connector, handoff.origin).storage;
+    const expiry = { ttlSeconds: Math.max(1, Math.ceil((handoff.expiresAt - Date.now()) / 1000)) };
+    return storage.compareAndSet(oauthConnectKeys.used(handoff.nonce), "used", outcome, expiry);
+}

package/dist/oauth-sealing.js

@@ -27,3 +27,23 @@ export function oauthSealerFor(ctx) {
 export function inheritOAuthSealer(from, to) {
     return attachOAuthSealer(to, sealers.get(from));
 }
+/** A separate HMAC key for browser handoffs, derived from the credential key. */
+export async function deriveOAuthHandoffKey(raw) {
+    const material = await crypto.subtle.importKey("raw", new Uint8Array(raw), "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new TextEncoder().encode("connecta:oauth-handoff:v1"),
+        info: new TextEncoder().encode("browser-connect"),
+    }, material, { name: "HMAC", hash: "SHA-256", length: 256 }, false, ["sign", "verify"]);
+}
+/** A purpose-specific MCP retry key, available only to the host's codec. */
+export async function deriveRequestStateKey(raw) {
+    const material = await crypto.subtle.importKey("raw", new Uint8Array(raw), "HKDF", false, ["deriveBits"]);
+    return new Uint8Array(await crypto.subtle.deriveBits({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new TextEncoder().encode("connecta:request-state:v1"),
+        info: new TextEncoder().encode("auth-elicitation"),
+    }, material, 256));
+}

package/dist/operator-record.d.ts

@@ -0,0 +1,137 @@
+import { type CallErrorDetails } from "./errors.js";
+import type { ConnectorStatus, Logger } from "./types.js";
+/** Where in connecta's work a failure happened. Closed, so it carries no prose. */
+type FailureStep = "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 declare const OAUTH_ERROR_CODES: ReadonlySet<string>;
+/** Inbound denial facts, never identity text or provider diagnostics. */
+export type AuthDenialReason = "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";
+/**
+ * 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 declare function labelErrorClass(ctor: {
+    readonly prototype: object;
+}, label: string): void;
+/**
+ * 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 declare function errorLabel(failure: unknown): string | undefined;
+/** Facts connecta derived about a failure where it saw it. */
+export interface FailureFacts {
+    step?: FailureStep;
+    /** Scheme, host, and port of the request that failed. */
+    origin?: string;
+    /** The HTTP status the downstream answered with. */
+    httpStatus?: number;
+    /** A registered OAuth `error` code the server named. */
+    oauthError?: string;
+}
+/** Note what connecta knows about `failure` for any record made of it later. */
+export declare function attachFailureFacts<T>(failure: T, facts: FailureFacts): T;
+/** The facts and class label of `from`, kept for `to` (its classified form, say). */
+export declare function carryFailureFacts<T>(from: unknown, to: T): T;
+/** What a failure record may be about. Only these fields are read. */
+export interface FailureSubject {
+    reason?: AuthDenialReason;
+    /** A registered connector's id. */
+    connector?: string;
+    /**
+     * The catalog entry the call resolved to, never a name alone: a tool is
+     * named only when connecta found it in that connector's catalog.
+     */
+    tool?: {
+        readonly name: string;
+    } | undefined;
+    source?: string;
+    /** A status state, for a status record. */
+    state?: ConnectorStatus["state"] | "failed";
+    /** Whether an OAuth start continued or restarted authorization. */
+    mode?: "continue" | "restart";
+    attempts?: number;
+    durationMs?: number;
+}
+declare const recordBrand: unique symbol;
+/** One failure as an operator may read it. Only `failureRecord` makes one. */
+export interface FailureRecord {
+    readonly [recordBrand]: true;
+    readonly reason?: AuthDenialReason;
+    readonly connector?: string;
+    readonly tool?: string;
+    readonly source?: string;
+    readonly state?: string;
+    readonly mode?: string;
+    readonly attempts?: number;
+    readonly durationMs?: number;
+    readonly step?: string;
+    readonly origin?: string;
+    readonly httpStatus?: number;
+    readonly oauthError?: string;
+    /** Classification code, such as `unavailable` or `connector_call_failed`. */
+    readonly code?: string;
+    readonly retryable?: boolean;
+    /** The error's class label, by identity, such as `TypeError`. */
+    readonly errorClass?: string;
+    /** A network errno or `timeout`. */
+    readonly errno?: string;
+}
+/**
+ * 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 declare function recordedToolName(entry: {
+    readonly name: string;
+}): string;
+/** Vouch for `details` as a classification connecta itself computed. */
+export declare function classifiedFailure<T extends CallErrorDetails>(details: T): T;
+/**
+ * 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 declare function failureRecord(subject: FailureSubject, failure?: unknown): FailureRecord;
+/**
+ * The events an operator log reports failures as. Closed: a new one is a
+ * reviewed line here, never a string assembled at the call site.
+ */
+export type FailureEvent = "negotiation cache read failed" | "negotiation cache write failed" | "connectorAccess grant is unreachable" | "call failed" | "input schema unusable; arguments are not validated" | "catalog read failed" | "catalog persistence failed" | "catalog invalidation failed" | "catalog refresh observation failed" | "catalog refresh failed; serving stale catalog" | "deferred catalog refresh failed" | "deferred catalog refresh could not attach to the runtime" | "catalog drift check failed" | "schema digest check failed; serving digested reviews as writes" | "credential shape read failed" | "credential test failed" | "credential test threw" | "session termination refused or failed; the downstream session may remain until its provider timeout" | "activity record failed" | "catalog drift record failed" | "activity read failed" | "OAuth start failed" | "OAuth disconnect failed" | "OAuth callback verifyState threw; no authorization code was exchanged" | "OAuth callback handoff could not be consumed; no authorization code was exchanged" | "MCP pool request denied" | "OAuth error callback consent could not be consumed; no authorization code was exchanged" | "MCP handler error" | "operator status" | "result paging unavailable" | "request failed" | "Clerk request denied" | "Clerk authentication failed";
+/**
+ * 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 declare function logFailure(logger: Pick<Logger, "info" | "warn" | "error">, event: FailureEvent, record: FailureRecord, level?: "info" | "warn" | "error"): void;
+/**
+ * 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 declare function describeFailure(connectorId: string, failure: unknown): string;
+/** A status whose message connecta wrote, such as an auth_required notice. */
+export declare function ownStatus<T extends ConnectorStatus>(status: T): T;
+/** An error status described from `failure`'s record, remembering the failure. */
+export declare function failureStatus(connectorId: string, failure: unknown): ConnectorStatus;
+/**
+ * `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 declare function boundedStatus(status: ConnectorStatus): ConnectorStatus;
+/** The failure connecta saw behind a status it described, if any. */
+export declare function statusFailure(status: ConnectorStatus): unknown;
+export {};