@zackbart/connecta 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.2 — 2026-08-18
+
+This patch closes the gap the RevenueCat rollout exposed on the same day 0.18.1
+shipped: a hosted-MCP connection could authenticate with OAuth from the
+Connections page or with a header literal baked into the deployment file, but
+never with a key an operator pastes on `/credentials` the way every `api()`
+connector already can. Now it can. Nothing breaks, no constructor changes, and a
+deployment that keeps its static keys in runtime secrets can ignore this release.
+Two things are worth reading before adopting the new shape: the operator vault
+(`credentials.encryptionKey`) must be configured, and a key pasted with a
+wrapped newline is refused before it is framed rather than echoed back by the
+runtime that rejects it.
+
+### Added
+
+- **`auth: { type: "credential" }` for `remoteMcp()` and every maintained
+  hosted connection.** The connector declares an operator credential slot on
+  `/credentials` (label and guidance from the provider, overridable), reads the
+  stored value on every request before trusting a cached client, and frames it
+  as `Authorization: Bearer <value>` by default — `header` and `scheme` are
+  configurable, `scheme: null` sends the value bare, and a scheme ending in
+  `Basic` base64-encodes it, which is how Mixpanel's documented
+  `Bearer Basic <base64(user:secret)>` is spelled. A missing or empty value is
+  `auth_required`, and `authorize_connector` returns the operator handoff to
+  `/credentials`; a deployment without a vault warns at construction and answers
+  `recovery: "unavailable"` at use. Rotation on `/credentials` takes effect on
+  the next call: a SHA-256 digest of the connected value is compared per
+  request (including against an in-flight connect) and a differing digest
+  closes the old client. The `/credentials` Test action connects with the
+  candidate and counts the catalog, and only when an operator presses it — the
+  #179 refusal of proactive probing stands, now written into P10. Provider
+  defaults: Stripe (requires `mode`, refuses `connectedAccount`), Linear
+  (Bearer, per Linear's MCP docs), Mixpanel (`Bearer Basic`, service account),
+  RevenueCat (single-project branch, "API v2 secret key") (#439).
+
+### Changed
+
+- **A stored credential never reaches an agent or operator surface, even
+  malformed.** The value is refused before framing if it carries a control
+  character (the wrapped-newline paste), with a message that names the problem
+  and not the value; behind that, any error whose message or `cause` chain
+  quotes the raw or framed value is replaced whole rather than redacted. Both
+  layers are tested independently (#439).
+
+- **Provider conventions P9 and P10 say what is now true.** P9 names both
+  headless shapes and requires the framing to match the provider's published
+  MCP contract; P10 is retitled to allow an operator-requested credential test
+  while forbidding any unasked probe (#439).
+
+- **Linear's headers example uses `Bearer`.** Linear's MCP server documents
+  `Authorization: Bearer <token>` for API keys; the bare form is its GraphQL
+  convention. Existing `headers` connectors are untouched (#439).
+
+## 0.18.1 — 2026-08-18
+
+This patch is the response to one long investigation run against a live
+deployment: a Mixpanel-and-Stripe user-journey reconstruction that rated the
+connectors trustworthy and the ceremony too high. Nothing breaks and no
+constructor changes. The two maintained guides now say the things that
+investigation had to discover the hard way — which questions Insights cannot
+answer, when Mixpanel's `false` is an absent property, which Stripe reads must
+be projected inside the sandbox and why that is a privacy boundary as much as
+a size one, and which fields Stripe search will not filter on. Beside them, a
+new maintained RevenueCat connection lands, with the fact that decides its
+deployment shape stated up front: a RevenueCat secret key reaches exactly one
+project, so several projects are several connectors. A deployment that
+constructs none of the three connections can ignore this release entirely.
+
+### Added
+
+- **`revenuecat()` — a maintained RevenueCat hosted-MCP connection** at
+  `@zackbart/connecta/providers/revenuecat`. OAuth by default (account-scoped:
+  the guide requires `list-projects` first and carries `project_id` into every
+  project-scoped call, stopping on ambiguity); an API v2 secret key as the
+  headless alternative, which binds the connector to one project — the guide's
+  first line names it, and a second project is a second connector with its own
+  key. All 95 documented tools are classified from RevenueCat's tools reference
+  (50 read-only, 15 additive, 29 destructive); `render-paywall-screenshot`
+  carries no access column there and fails closed. Borderline verdicts are
+  argued beside the rows they decide: `create-webhook-integration`,
+  `grant-customer-entitlement`, and `assign-customer-offering` are destructive
+  on consequence, not on verb. RevenueCat publishes six per-domain rate limits
+  and one admission rule cannot honestly cover 95 tools, so `callAdmission`
+  stays with the operator and the guide states the numbers. The maintainer-run
+  drift check accepts `revenuecat` behind `CONNECTA_DRIFT_REVENUECAT_KEY`; no
+  schema digests are recorded until a maintainer runs `--record` against a live
+  project (#433).
+
+### Changed
+
+- **The Mixpanel guide says what Insights cannot answer.** One analysis is one
+  `execute_code` program with one `Get-Query-Schema` fetch; per-user event
+  timelines and sequence questions are out of reach through `Run-Query`
+  (`Get-User-Replays-Data` covers one user only where session replay is on);
+  `false` on a boolean property may be an absent one and must be confirmed with
+  `List-Properties` before it becomes a signal; breakdown responses are
+  flattened one row per combination inside the program with `$overall`
+  dropped. Convention P7 gains the rendering-rule clause this rests on (#430).
+
+- **The Stripe guide names the reads that must be projected and the fields
+  search cannot filter.** Any `stripe_api_read` list or `stripe_api_search`
+  that returns full objects belongs inside `execute_code`, projected before
+  `return` — the reduction keeps customer PII out of the transcript, not only
+  bytes. Charges search takes a documented field set with no `payment_intent`;
+  follow the PaymentIntent's `latest_charge` instead. The account → search →
+  details → read sequence is one program, and decline outcomes are `outcome`,
+  `failure_code`, `failure_message` on the charge (#431).
+
 ## 0.18.0 — 2026-08-13
 
 This minor release spends fewer tokens before the first call and answers

package/README.md

@@ -2,133 +2,94 @@
 
 ![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
-One place for AI agents to connect to the tools you choose.
+One MCP endpoint. The integrations you chose. Your agent reaches them by
+writing code instead of loading a thousand tool definitions.
 
-Connecta gives an agent a single MCP endpoint instead of making it connect to
-every service separately. You decide which integrations are available and
-Connecta holds their credentials, and the agent mostly works by writing
-ordinary JavaScript that Connecta runs in a sandbox next to them — with a few
-explicit tools for the jobs a program is the wrong shape for, destructive calls
-among them.
+## The mental model
 
-```mermaid
-flowchart LR
-    Agent["AI agent"]
-    Integrations["The integrations you chose"]
-
-    subgraph Connecta["Connecta: one MCP endpoint; credentials stay here"]
-        Sandbox["execute_code<br/>server-side sandbox"]
-        Explicit["Explicit tools<br/>destructive calls, search, auth"]
-    end
-
-    Agent -->|"writes a program"| Sandbox
-    Agent -->|"one deliberate call"| Explicit
-    Sandbox --> Integrations
-    Explicit --> Integrations
-```
+You ask your agent a question that touches a service — Linear, Stripe, an
+internal API, anything you have connected. Here is what happens:
 
-## Why Connecta
+1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+   no matter how many services sit behind it.
+2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
+   your integrations. The program can search for tools, call them, chain the
+   calls, and shape the result.
+3. Only the answer comes back into the agent's context — not raw pages of
+   API output.
+4. If the agent wants to change something — create, update, delete — it
+   cannot do that from a program. It makes one explicit call, and your MCP
+   client can put that call in front of you first.
 
-- **One connection.** Configure clients once, even as integrations change.
-- **Seven tools, not seven hundred.** A program can search the catalog, chain
-  calls, and trim the results before the agent ever sees them — so nothing has
-  to be loaded up front.
-- **Safer access.** Credentials stay server-side — the program never sees them
-  — and consequential actions remain explicit and individual.
-- **Named client access.** A Clerk operator can issue and revoke one-time,
-  hashed Bearer tokens for MCP clients that support header authentication.
-- **Your deployment.** Connecta runs on Node, Docker, or Cloudflare Workers,
-  with configuration you can review and version.
+Credentials never leave the server. The program never sees them, and neither
+does the agent.
 
-## Start here
+```mermaid
+flowchart TB
+    Client["Your MCP client<br/>Claude, Cursor, …"]
 
-Create the prescribed Node deployment:
+    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools only"]
+        Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
+    end
 
-```sh
-npx @zackbart/connecta init my-connecta
-cd my-connecta
-npm install
-CONNECTA_TOKEN=dev-token npm start
-```
+    Integrations["The integrations you chose<br/>Linear · Stripe · Notion · your HTTP API · any MCP server"]
 
-Point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer dev-token`. The generated project is deliberately small:
-
-```text
-my-connecta/
-├── src/index.ts       # connectors, auth, storage, public URL
-├── src/file-activity.ts # deployment-owned activity store, wired on request
-├── package.json       # exact Connecta and QuickJS versions
-├── tsconfig.json
-├── Dockerfile         # the same source, containerized
-├── docker-compose.yml # one service, state on a named volume
-├── .dockerignore
-├── .env.example
-├── .gitignore
-├── AGENTS.md
-├── CLAUDE.md -> AGENTS.md
-└── README.md
+    Client -->|"one connection"| Sandbox
+    Client --> Explicit
+    Sandbox -->|"reads"| Integrations
+    Explicit -->|"writes"| Integrations
 ```
 
-The same project runs as a long-lived container without changing a line of it:
-
-```sh
-cp .env.example .env    # set CONNECTA_TOKEN
-docker compose up -d --build
+This is the kind of thing the agent writes, not you:
+
+```js
+async () => {
+  const { nodes } = await tracker.list_issues({ state: "started" });
+  const byOwner = {};
+  for (const issue of nodes) {
+    (byOwner[issue.assignee?.name ?? "unassigned"] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
 ```
 
-For an agent setting this up, the contract is:
-
-1. Edit `src/index.ts`; do not copy Connecta internals into the deployment.
-2. Keep the required `executor: quickJsExecutor()` configuration; without an
-   executor the deployment refuses to boot.
-3. Keep secrets in environment variables or a secret store, never source.
-4. Add connectors explicitly: import a maintained prebuilt provider
-   constructor when one exists, otherwise write a deliberate `remoteMcp()` or
-   `api()` connector. There is no registry to browse and nothing registers
-   itself.
-5. Run `npm run typecheck`, start the server, and run
-   `CONNECTA_TOKEN=... npm run doctor`. Doctor checks health, the executor, and
-   the exact seven-tool model-facing surface, then executes a harmless sandbox
-   program. The bearer stays in the environment rather than command history.
-
-The operator surface is the same in both shapes and off until you say so:
-Clerk sign-in, the credential vault, access-token issuance, and payload-free
-activity ship as commented configuration, each one a variable and an
-uncommented block away. The generated `README.md` walks through all four, and
-the [Worker example](./examples/worker/) does the same for KV and D1.
-
-Already have a deployment on an older version? `init` deliberately refuses to
-merge into it, so bringing one current is its own procedure:
-[Upgrading an existing deployment](./documentation/upgrading.md) is the
-runbook, written for the agent working inside that project.
-
-The template refuses to merge into an existing directory, so initialization
-cannot overwrite another project. Its generated programs have no filesystem,
-environment, arbitrary network, imports, or timers; only explicitly read-only
-connector tools are reachable. Unannotated or write-capable calls stay
-individual and cross `call_destructive_tool`, where the MCP host can ask the
-operator for approval.
-
-The Node template also pins its one approved dependency install script:
-esbuild, which `tsx` needs to run the deployment source. A dependency update
-that adds or changes an install script fails the package smoke until reviewed.
-
-There are two deployment shapes and no others:
-
-- [Node, local or Docker](./templates/node/) — what `init` copies
-- [Cloudflare Worker deployment](./examples/worker/)
-- [Subsystem documentation](./documentation/)
-
-Every deployment configures a sandbox: QuickJS on Node or a Dynamic Worker on
-Cloudflare. Construction fails with an actionable error when the executor is
-missing, so the model-facing interface is always the same seven tools.
-
-## Project status
-
-Connecta is built for its author's deployments first and is still evolving.
-Breaking changes are expected before 1.0.
-
-Read the [ethos](./ethos.md) for the product's principles, the
-[changelog](./CHANGELOG.md) for releases, and [security policy](./SECURITY.md)
-for vulnerability reporting.
+Fifty issues in, one small object out. Your context window notices.
+
+## What you can do with it
+
+- **Put every MCP server you use behind one connection.** Add or remove
+  services in a config file; your client never changes.
+- **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
+  generated tool sprawl is the problem, not the fix.
+- **Use maintained connections** for Cloudflare, Linear, Mixpanel, Notion,
+  RevenueCat, and Stripe — known endpoints, auth defaults, and vetted read/write
+  classifications, imported one at a time.
+- **Let the agent work in code.** Search, chain, filter, join, and reduce
+  inside the sandbox instead of round-tripping every call through the model.
+- **Keep writes deliberate.** Only tools marked read-only run in a program.
+  Everything else is a separate, visible call your client can gate.
+- **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,
+  from the same small deployment file.
+
+There is also an operator surface, off until you turn it on: sign-in, an
+encrypted credential vault with rotation, revocable per-client tokens, and a
+payload-free activity log.
+
+Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
+service. Those are decisions, and the [ethos](./ethos.md) records each one
+and why.
+
+## Getting started
+
+Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
+ask it to set up a Connecta deployment; the
+[documentation](./documentation/) covers every subsystem if you want to go
+deeper, and [upgrading](./documentation/upgrading.md) an existing deployment
+is its own runbook.
+
+## Status
+
+Built for its author's deployments first and published openly. Breaking
+changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
+[security policy](./SECURITY.md).

package/dist/connectors/remote-mcp.d.ts

@@ -1,12 +1,58 @@
 import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
-import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorUsageGuide, Logger } from "../types.js";
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
+/**
+ * A static downstream credential the operator supplies at `/credentials`
+ * rather than the deployment baking into its source.
+ *
+ * The connector, its endpoint, and the credential *slot* stay declared in
+ * code; only the secret arrives through the operator route, exactly as for
+ * `api()`. One reserved `value` field, deliberately: a header is assembled
+ * from a name, a framing scheme, and one secret, and anything that needs two
+ * secrets composed into one header is a provider integration, not a proxy
+ * config ([#439](https://github.com/zackbart/connecta/issues/439)).
+ */
+interface RemoteMcpCredentialAuth {
+    type: "credential";
+    /**
+     * Operator-facing slot description rendered on `/credentials`. Defaults to
+     * `{ label: "API key" }`; a maintained provider passes the name the provider
+     * itself uses. Named `fields` are refused — this shape reads the reserved
+     * `value` field only.
+     */
+    credential?: ConnectorCredentialConfig;
+    /** Header the credential rides. Defaults to `Authorization`. */
+    header?: string;
+    /**
+     * Framing token placed before the value. Defaults to `"Bearer"`. `null` (or
+     * an empty string) sends the stored value verbatim, for an endpoint that
+     * reads a bare key. A scheme whose last token is `Basic` declares
+     * HTTP Basic credentials: the stored `user:secret` is base64-encoded first,
+     * so `"Basic"` produces `Basic <base64>` and Mixpanel's documented
+     * `"Bearer Basic"` produces `Bearer Basic <base64>`.
+     */
+    scheme?: string | null;
+}
 export type RemoteMcpAuth = {
     type: "headers";
     headers: Record<string, string>;
-} | {
+} | RemoteMcpCredentialAuth | {
     type: "oauth";
 };
+/**
+ * Apply a maintained provider's slot copy and header framing to credential
+ * auth the deployment left bare.
+ *
+ * A provider knows what its own key is called and how the endpoint expects it
+ * framed; a deployment that states either one keeps its answer. Every other
+ * auth shape passes through untouched, so a provider can hand this its whole
+ * `auth` option without branching first.
+ */
+export declare function withCredentialDefaults(auth: RemoteMcpAuth, defaults: {
+    credential: ConnectorCredentialConfig;
+    /** Provider framing; omit to leave the `Bearer` default in place. */
+    scheme?: string | null;
+}): RemoteMcpAuth;
 export type RemoteMcpRedirectPolicy = "none" | "same-origin";
 export interface RemoteMcpOptions {
     url: string;
@@ -90,3 +136,4 @@ export declare function redirectSafeFetch(connectorId: string, policy?: RemoteMc
  * server or hide other connectors).
  */
 export declare function remoteMcp(id: string, opts: RemoteMcpOptions): Connector;
+export {};