@outcrawl/sdk 0.1.0

package/dist/types/_deps/integrations/connector.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The connector registry: what a workspace has connected, and what it cannot.
+ *
+ * Outcrawl is an MCP **server** inbound — `packages/mcp` — and this package is
+ * the outbound half. A workspace connects Gmail, Slack or Twilio and a run
+ * calls those tools mid-task. The two directions share nothing but the
+ * protocol; the inbound server is untouched by any of this.
+ *
+ * This module holds the row and the rules that decide whether a row may exist
+ * at all. The rules are the security surface of the whole feature, so they are
+ * here, in one place, with their reasoning, rather than distributed across a
+ * handler and a client.
+ */
+/**
+ * How we reach a connected MCP server. **HTTPS, and there is no second arm.**
+ *
+ * ## Why stdio is refused, and why the refusal is a union arm and not an omission
+ *
+ * The MCP ecosystem's default transport is stdio: a client spawns
+ * `npx -y @modelcontextprotocol/server-gmail` and speaks JSON-RPC over its
+ * pipes. Supporting that here would mean `POST /v1/integrations` accepts a
+ * command line and a fleet Mac executes it.
+ *
+ * A fleet Mac is multi-tenant. It holds `TICKET_SECRET`, profile blobs, and
+ * other accounts' live browser contexts, and there is no sandbox between a
+ * spawned child process and any of that. A `stdio` field on this type is
+ * therefore a JSON-schema'd remote code execution endpoint running as the
+ * worker user, reachable by anyone with an API key.
+ *
+ * An allowlist does not fix it. The canonical invocation is `npx -y <package>`,
+ * which is `npx` fetching arbitrary code off the network at call time — **an
+ * allowlist of names, not of code.** Pinning versions moves the trust to a
+ * registry we do not control; vendoring the servers means shipping a Gmail
+ * client in our worker bundle and calling it an integration.
+ *
+ * And it buys nothing we need. Gmail, Slack and Twilio — the three the product
+ * was scoped around — all publish hosted HTTP MCP endpoints. Every use case
+ * the feature exists for is served without ever spawning a process.
+ *
+ * So this is a discriminated union with exactly one arm. That is the same
+ * discipline `mcpTool: string | null` uses in the capability registry: a
+ * declined option must not be spellable the same way as a forgotten one.
+ * Adding a `stdio` arm later — when there is a per-run sandbox to run it in —
+ * is a compile error at every `switch` in this package until somebody has
+ * handled it deliberately.
+ */
+export type ConnectorTransport = {
+    readonly kind: 'http';
+    /** Absolute `https://` endpoint speaking MCP over HTTP. */
+    readonly url: string;
+};
+export declare const CONNECTOR_TRANSPORT_KINDS: readonly ["http"];
+/**
+ * How we authenticate to the remote server — **by handle, never by value.**
+ *
+ * `secret` is a handle into the workspace secrets store (`@outcrawl/core`'s
+ * `secrets.*` capabilities, bare string, `^[a-z0-9][a-z0-9_-]{0,63}$`). It is
+ * what the row stores, what `integrations.list` returns and what appears in
+ * any log. The plaintext is resolved at the instant of a call, by the tier
+ * that makes the call, and nothing here ever holds one.
+ *
+ * There is no second credential store. A connector that wanted its own would
+ * be a second place a customer's Gmail token lives, with its own encryption
+ * decision, its own rotation story and its own bugs.
+ */
+export type ConnectorAuth = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'bearer';
+    readonly secret: string;
+} | {
+    readonly kind: 'header';
+    readonly header: string;
+    readonly secret: string;
+};
+export declare const CONNECTOR_AUTH_KINDS: readonly ["none", "bearer", "header"];
+/**
+ * THE ROW IS THE RESPONSE. `integrations.list` answers these verbatim and
+ * there is no projection in front of it, unlike `secrets.list`, which has to
+ * withhold a ciphertext.
+ *
+ * That is not a shortcut, it is the property: a connector row holds a secrets
+ * store HANDLE and never a value, so there is nothing on it to withhold. A
+ * `ConnectorView` that stripped fields would imply the row has some — and the
+ * day somebody adds a field worth hiding, they will add it to a type nobody
+ * reads twice. Making the row publishable in full is what keeps it honest.
+ */
+export interface Connector {
+    readonly id: string;
+    /**
+     * The name the model addresses this connector by, and the left half of every
+     * `<connector>.<tool>` the prompt shows. Lowercase, stable, unique per
+     * account: `gmail`, `slack`, `twilio`.
+     */
+    readonly name: string;
+    readonly transport: ConnectorTransport;
+    readonly auth: ConnectorAuth;
+    /**
+     * The tools this connector may expose, or `null` for every tool the remote
+     * advertises.
+     *
+     * Required-and-nullable rather than optional, on the registry's own rule: "I
+     * reviewed the catalogue and all of it is fine" and "nobody said" are
+     * different facts and must not be the same bytes. This is the field a
+     * customer reads to answer *what can an agent reach outside the browser*,
+     * and an undefined that renders as "everything" is the one answer nobody
+     * consented to.
+     */
+    readonly tools: readonly string[] | null;
+    readonly createdAt: string;
+}
+/** A connector on its way in. No id and no timestamp: both are the store's. */
+export interface ConnectorInput {
+    readonly name: string;
+    readonly transport: ConnectorTransport;
+    readonly auth: ConnectorAuth;
+    readonly tools: readonly string[] | null;
+}
+/**
+ * Whether a hostname is an IP literal in a range that is not on the public
+ * internet.
+ *
+ * ## What this closes, and — as importantly — what it does not
+ *
+ * It closes the direct attack: `POST /v1/integrations` with
+ * `https://169.254.169.254/latest/meta-data/` or `https://10.0.0.5/`, which
+ * would otherwise make our own egress into a reader for whatever is on the
+ * other side. That is worth closing on its own and it is cheap.
+ *
+ * It does NOT close DNS rebinding — a name that resolves publicly when this
+ * runs and privately when the call is made. Closing that needs the resolved
+ * address at connect time and at call time, and the tier that makes the call
+ * is a Cloudflare Worker, whose runtime exposes no resolver and no socket. So
+ * this is stated as a partial defence rather than asserted as a complete one.
+ *
+ * The residual risk is bounded by WHERE the call runs, which is the second
+ * reason the tool call is proxied through the edge rather than made from a
+ * fleet Mac: a Mac sits on a private network with the rest of the fleet on it,
+ * and the Worker does not.
+ */
+export declare function isPrivateAddressLiteral(host: string): boolean;
+/**
+ * The one rule for "an endpoint this product will make an authenticated
+ * outbound request to". Throws `BadRequestError` naming the field.
+ */
+export declare function connectorUrl(value: unknown): string;
+/**
+ * Read a connector off a request body. Throws `BadRequestError` naming the
+ * field, which is what the API surfaces as a 400.
+ */
+export declare function parseConnectorInput(body: Readonly<Record<string, unknown>>): ConnectorInput;
+/** Every field `integrations.connect` accepts. */
+export declare const CONNECTOR_FIELDS: readonly ["name", "transport", "auth", "tools"];