@zackbart/connecta 0.30.0 → 0.32.0

package/documentation/provider-auth-migration.md

@@ -0,0 +1,308 @@
+# Provider auth migration
+
+Use this upgrade guide when moving a Stripe, Notion, Vercel, or Cloudflare
+deployment from 0.30 to 0.31, where `auth` selects each provider's
+implementation ([#801](https://github.com/zackbart/connecta/issues/801)).
+The [0.31.0 release notes](https://github.com/zackbart/connecta/blob/main/release-notes/0.31.0.md) summarize the change.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
+version changes; [integrating services](./integrating.md) covers new connectors.
+
+A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
+hosted MCP server, OAuth only. A key type connects Connecta's REST connector
+with an operator-managed credential. There is no default, and one connector id
+uses one implementation: configure two ids for both. The
+[decision record](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
+explains why.
+
+## Stripe
+
+Stripe's hosted MCP server stops accepting secret keys and untagged
+restricted keys on 2026-10-31; Stripe still documents agent-tagged restricted
+keys for it. Connecta's hosted Stripe connection is OAuth only either way, and
+every key, tagged or not, uses the REST connector. Every `stripe()` call must
+now name `auth`:
+
+```ts
+connectors: [
+  stripe("stripe", {
+    purpose: "Organization billing",
+    auth: { type: "oauth" },
+  }),
+  stripe("stripe_live", {
+    purpose: "Live billing",
+    auth: { type: "apiKey" },
+    mode: "production",
+  }),
+  stripe("stripe_sandbox", {
+    purpose: "Rehearsal",
+    auth: { type: "apiKey" },
+    mode: "sandbox",
+  }),
+  stripe("stripe_merchant", {
+    purpose: "One connected merchant",
+    auth: { type: "apiKey" },
+    mode: "production",
+    connectedAccount: "acct_…",
+  }),
+];
+```
+
+| 0.30 configuration                               | Now                                                                                                                  |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| No `auth`, or `auth: { type: "oauth" }`          | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, guide conventions, and grant.                            |
+| `auth: { type: "headers", headers }` with `mode` | `auth: { type: "apiKey" }` with `mode`. Paste the key into the connection in the operator UI; literal keys are gone. |
+| `auth: { type: "credential" }` with `mode`       | `auth: { type: "apiKey" }` with `mode`. A key stored for the same connector id carries over; run its Test action.    |
+| `connectedAccount` with `headers` auth           | `connectedAccount` with `auth: { type: "apiKey" }`; it now works with an operator-managed key.                       |
+| `mode` or `connectedAccount` with OAuth          | Refused by name at construction, as before.                                                                          |
+
+The key connector keeps Stripe's tool names (`stripe_api_search`,
+`stripe_api_details`, `stripe_api_read`, `stripe_api_write`,
+`get_stripe_account_info`, and `get_balance_summary`) with Connecta's own
+contracts: search finds operations in a pinned API index, every call is
+checked against that index before it is sent, results arrive as
+`{ status, data, page? }`, and POST writes send the caller's `idempotencyKey`
+or a generated one as `Idempotency-Key` and return it (DELETE sends none).
+Every request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the
+version of the pinned index, whatever the account's default API version, so
+response shapes and accepted parameters follow that version. Check fields
+your programs rely on with `stripe_api_details`.
+A key whose `sk_live_`/`rk_live_` or `sk_test_`/`rk_test_` prefix contradicts
+`mode` is refused before any request. Organization keys (`sk_org_…`) need a
+`Stripe-Context` header the connector does not send; use an account key.
+
+Lost on the key path: natural-language Sigma (`stripe_analytics`), metrics,
+documentation search, the implementation planner, reports, and feedback exist
+only on the hosted OAuth connection. Programs calling those tools on a key
+connector need an OAuth connector beside it. The
+[Stripe skill](https://github.com/zackbart/connecta/blob/main/src/providers/stripe/SKILL.md)
+owns the conventions for both.
+
+## Notion
+
+Every `notion()` call must now name `auth`. 0.30 defaulted to hosted MCP and
+selected the REST interface with `surface: "api"`; `surface` is gone:
+
+```ts
+connectors: [
+  notion("notion", { purpose: "Workspace content as the signed-in user", auth: { type: "oauth" } }),
+  notion("notion_bot", { purpose: "Internal integration content", auth: { type: "token" } }),
+]
+```
+
+| 0.30 configuration                                                                                                                        | Now                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`                                                                                                         | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, grant, and optional `callAdmission`.                     |
+| `surface: "api"`                                                                                                                          | `auth: { type: "token" }`. The integration token stored for the same connector id carries over; run its Test action. |
+| `credentialLabel` or `defaultPageSize`                                                                                                    | Token only, as before. Under OAuth they are refused by name at construction.                                         |
+| `integration_search`, `_get_page`, `_get_page_content`, `_get_data_source_schema`, `_query_data_source`, `_create_page`, `_append_blocks` | Unchanged names and contracts. `integration_append_blocks` also takes `checklist`.                                   |
+| `integration_get_database`                                                                                                                | `notion_api_read` `GET /v1/databases/{database_id}`.                                                                 |
+| `integration_get_page_property`                                                                                                           | `notion_api_read` `GET /v1/pages/{page_id}/properties/{property_id}`; `truncated_properties` names it.               |
+| `integration_list_users`, `integration_get_self`                                                                                          | `notion_api_read` `GET /v1/users` or `GET /v1/users/me`.                                                             |
+| `integration_list_comments`, `integration_add_comment`                                                                                    | `notion_api_read` `GET /v1/comments`; `notion_api_write` `POST /v1/comments`.                                        |
+| `integration_update_page_properties`, `integration_trash_page`                                                                            | `notion_api_write` `PATCH /v1/pages/{page_id}` with `properties`, or `in_trash` to trash or restore.                 |
+
+The token connector gains Connecta's generic REST tools over Notion's pinned
+API index (`notion_api_search`, `notion_api_details`, `notion_api_read`,
+`notion_api_write`), so every public operation is reachable with the bot's
+token: views, page moves and Markdown, meeting notes, custom agents and
+sessions, file uploads by `external_url`, and data source changes. Every call
+is checked against the index before it is sent, and results arrive as
+`{ status, data, page? }`. The read-only POST queries (search, data source,
+meeting notes, agents, sessions, and session events) use `notion_api_read`;
+`page.in: "body"` says their cursor goes back in the body. Notion's OAuth token
+endpoints and multipart file sends are refused. The 0.29 reconciliation table
+and the `surface: "api"` complement rules no longer apply to Notion.
+
+Lost per mode. A token connector acts as the integration bot, never as a
+person, and has none of the hosted MCP's search across connected apps, page
+duplication, team and skill search, attachment downloads, or page-to-skill
+conversion. An OAuth connector acts as the user, and has none of the generic
+REST tools or the `integration_*` projections and authoring helpers. Configure
+both ids when a deployment needs both; a failed call is never retried on the
+other. The [Notion skill](https://github.com/zackbart/connecta/blob/main/src/providers/notion/SKILL.md)
+owns the conventions for both.
+
+## Vercel
+
+Every `vercel()` call must now name `auth`. `surface` is gone, and so are the
+0.29 ownership rules that made the REST complement refuse whatever the hosted
+server also covered: each implementation is complete on its own.
+
+```ts
+connectors: [
+  vercel("vercel", { purpose: "Deployment diagnosis", auth: { type: "oauth" } }),
+  vercel("vercel_rest", { purpose: "Production apps", auth: { type: "token" }, teamId: "team_…" }),
+]
+```
+
+| 0.30 configuration                                                    | Now                                                                                                                                                           |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`                                     | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, and grant.                                                                                        |
+| `surface: "api"` with `teamId` or `baseUrl`                           | `auth: { type: "token" }` with the same options. A token stored for the same connector id carries over; run its Test action.                                  |
+| `defaultPageSize`                                                     | Removed (it already had no effect). Pass `limit` in `query`, and follow `page.next` as `page.param`.                                                          |
+| `teamId` or `baseUrl` with OAuth                                      | Refused by name at construction.                                                                                                                              |
+| `vercel_api_get`, `vercel_api_mutate`                                 | `vercel_api_read` and `vercel_api_write`: `query` is a JSON object, not name/value pairs, and `teamId: null` replaces `personalAccount: true`.                |
+| `verify_project_domain`, `remove_project_domain`, `delete_deployment` | `vercel_api_write` with the operation from `vercel_api_search`, such as `DELETE /v13/deployments/{id}`.                                                       |
+| `vercel_api_upload` with any path and headers                         | `vercel_api_upload` on octet-stream operations in the index (`POST /v2/files`, project avatars, Remote Cache artifacts); Connecta computes `x-vercel-digest`. |
+
+The token connector serves `vercel_api_search`, `vercel_api_details`,
+`vercel_api_read`, and `vercel_api_write` over Vercel's OpenAPI document,
+pinned by content hash because Vercel does not version it. Every call is
+checked against the pinned index before it is sent, and results arrive as
+`{ status, data, page? }`. It adds `list_teams`, the value-safe environment
+variable tools (`list_project_env_vars`, `upsert_project_env_var`,
+`update_project_env_var`, `delete_project_env_var`),
+`get_deployment_build_logs` (build events, never following), `get_runtime_logs`
+(the runtime stream, stopped after `waitMs` or `maxRows`), and
+`vercel_api_upload`.
+
+Value safety follows a reviewed table (`src/providers/vercel/value-safety.ts`).
+Every operation whose response schema in the pinned spec may carry a credential
+or a stored secret has a verdict: refused (credential minting, Connect
+authorization, decrypted environment values, Global Config items and tokens,
+domain transfer codes, KMS signing), redacted at reviewed field paths
+(environment values, protection-bypass secrets, deploy hook URLs, drain and
+webhook headers and destination URLs beyond their origin, external route and
+redirect destinations beyond their origin, the args and values of every header,
+cookie, and query rule (route transforms and conditions, firewall conditions), team invite codes, synced Global Config items, URL credentials, and signing
+secrets, including the one a new webhook or drain returns at creation), or
+safe with a reason. Detection reads field names, field descriptions, and
+operation descriptions, so a project transfer request (whose code lets another
+team claim the project) is refused too. A test fails when
+a newly flagged operation has no verdict. A key-name heuristic covers every
+other body as defense in depth. Secret-family failures carry fixed messages
+instead of Vercel's text, and every other reviewed operation also withholds that
+text ([value safety](#value-safety-on-every-key-connector)). Read or rotate withheld secrets in the Vercel
+dashboard. A domain move-out is refused because its answer is a transfer token.
+
+Lost on the token path: documentation search, runtime error clusters, toolbar
+threads, agent runs, web analytics summaries, purchase quotes and guided
+purchases, `deploy_to_vercel`, and access grants for protected URLs exist only
+on the hosted OAuth connection. Programs calling those tools need an OAuth
+connector beside the token connector.
+
+The hosted connection now lists `filter_project_envs`, `get_project_env`,
+`create_project_env`, and `edit_project_env`, which 0.29 hid. The two reads can
+return decrypted values, so they are reviewed as writes, and a `readOnly`
+endpoint refuses them. Vercel admits only reviewed and approved MCP clients to its
+hosted server; if authorization is refused for that reason, the deployment
+needs Vercel's approval or a token connector. The
+[Vercel skill](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/SKILL.md)
+owns the conventions for both.
+
+## Cloudflare
+
+Every `cloudflare()` call must now name `auth`. 0.30 defaulted to hosted MCP
+when `surface` was omitted; that default is gone with `surface` itself:
+
+```ts
+connectors: [
+  cloudflare("cloudflare", {
+    purpose: "Estate changes",
+    auth: { type: "oauth" },
+  }),
+  cloudflare("cloudflare_api", {
+    purpose: "Production DNS and Workers",
+    auth: { type: "apiToken" },
+    accountId: "<account id>",
+    zoneId: "<zone id>",
+    pin: { accountIds: ["<account id>"] },
+  }),
+  cloudflare("cloudflare_legacy", {
+    purpose: "Legacy zones behind a user key",
+    auth: { type: "globalApiKey" },
+    pin: { zoneIds: ["<zone id>"] },
+  }),
+];
+```
+
+| 0.30 configuration                                   | Now                                                                                                                                      |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`, with OAuth        | `auth: { type: "oauth" }`. Same endpoint, catalog, and grant.                                                                            |
+| `surface: "mcp"` with `auth: { type: "credential" }` | `auth: { type: "apiToken" }`: bearer tokens no longer reach `mcp.cloudflare.com`. A token stored for the same connector id carries over. |
+| `surface: "api"` (API token)                         | `auth: { type: "apiToken" }` with the same `accountId`, `zoneId`, `baseUrl`, and `maxConcurrency`.                                       |
+| `surface: "api"`, `authentication: "globalApiKey"`   | `auth: { type: "globalApiKey" }` plus `pin: { accountIds, zoneIds }`, or `unpinned: true` to accept the user's whole estate.             |
+| `credential` override                                | Removed; the credential slot's copy is fixed.                                                                                            |
+| `callAdmission` with hosted MCP                      | Unchanged under `auth: { type: "oauth" }`.                                                                                               |
+
+The key connector is complete on its own. JSON writes that 0.30 refused on an
+API token (they belonged to hosted `execute`) go through
+`cloudflare_api_write`, checked against a pinned API index before they are
+sent. The 23 hand-written reads (`get_zone`, `list_dns_records`,
+`list_r2_objects`, `list_pages_deployments`, and the rest) are replaced by
+`cloudflare_api_read` on the same paths; results are Cloudflare's own
+`result`, unprojected, so programs pass `select` instead of reading the old
+projections. `list_accounts`, `list_zones`, and `cloudflare_api_upload` keep
+their names (upload now takes `parts` for multipart); `verify_api_token` and
+`verify_global_api_key` become `verify_credential`; `cloudflare_api_get` and
+`cloudflare_api_mutate` become `cloudflare_api_read` and `cloudflare_api_write`.
+`graphql_query` is new.
+
+Credentials stay in the dashboard. The key connector refuses every operation
+that mints, rotates, or returns a credential (API tokens, Access service
+tokens, R2 temporary credentials, signing keys, direct-upload URLs, deploy
+hooks) and redacts stored secrets on every result. A pinned connector refuses
+operations that name no account or zone unless they are reviewed safe, such
+as `/certificates` and `/memberships/{id}`.
+
+Read-only endpoints: hosted `execute` is always a write, even for a program
+that only reads, so a `readOnly` endpoint on an OAuth connector reaches only
+`search`.
+Use an API-token connector for read-only API access.
+
+Lost on each path. OAuth has no index validation, named tools, GraphQL tool,
+upload tool, or pin; Cloudflare's OAuth grant is the only boundary. A key has
+no hosted `search` over Cloudflare's live OpenAPI document; the pinned index
+replaces it and `providers:check` reports when it falls behind. A Global API
+Key cannot reach R2, which accepts API tokens only. The
+[Cloudflare skill](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/SKILL.md)
+owns the conventions for both.
+
+## Value safety on every key connector
+
+All four key connectors now share one value-safety mechanism: a reviewed
+table per vendor over every operation the detector flags in the pinned spec,
+one redaction pass on every result, and one error policy
+([architecture](./architecture.md#value-safety-for-rest-vendors)). Results
+lose fields they returned before. A `"[redacted]"` value is never the real
+one; read or rotate withheld secrets in the vendor's dashboard.
+
+- **Stripe** refuses operations that hand out a credential: ephemeral keys,
+  Terminal connection tokens, account links, Express login links, account and
+  customer sessions, billing portal sessions, file link creation, Financial
+  Connections session creation, and the meter event session. Results redact
+  client secrets (PaymentIntents, SetupIntents, Checkout and Identity
+  sessions, Sources, Financial Connections, invoice confirmation secrets),
+  webhook and event destination signing secrets, Apps secret payloads,
+  app-install authorization codes, Terminal Wi-Fi passwords, forwarded
+  request header values, and Issuing card numbers and CVCs; webhook, file
+  link, and pre-signed import URLs keep only their scheme and host, and the
+  rules follow each object into expansions, lists, and events (an expanded
+  File's links, an event's `previous_attributes`). Identity verification
+  URLs are unchanged. A Checkout Session's URL is returned whole only for a
+  guest payment session (`mode: "payment"`, no `customer` or
+  `customer_account`, no customer creation, no saved payment method options);
+  any other session returns only its scheme and host, because its page can
+  show, reuse, or remove a customer's saved payment methods. v2 account
+  links and Terminal onboarding links are refused too. Issuing `number` and
+  `cvc` expansions are refused on every Issuing path, not only cards.
+  Failures of credential-bearing operations keep Stripe's type, code, and
+  param but not its message. Create client-side sessions and links from your
+  own server code.
+- **Notion** results withhold the signature, credential, and security-token
+  parameters of pre-signed file URLs, so a returned file URL no longer
+  downloads; credential-named fields, including database properties named
+  like credentials, read as `"[redacted]"`. Failures of the OAuth, file
+  upload, bot user, and agent operations keep Notion's code but not its
+  message.
+- **Vercel** replaces environment values with `"[redacted]"` instead of
+  dropping the field, and withholds Vercel's error text for every reviewed
+  operation and every operation whose request takes a credential-named
+  field, not only secret families. Audit event invite codes, integration
+  drain headers, and route header values are redacted too.
+- **Cloudflare** redacts Hyperdrive database passwords, RealtimeKit storage
+  credentials, transform-rule header values, and dispatch binding values,
+  and reduces notification, RealtimeKit, and data security webhook
+  destinations to their scheme and host. A credential-named field now loses
+  its whole value, not only its strings (a `cookies` list, a variable named
+  `API_KEY`).

package/documentation/provider-migration-0.29.md

@@ -11,6 +11,11 @@ BePresent and One&Many use Notion and Cloudflare; their actual grants and
 connector ids must be checked in deployment configuration before that release.
 The provider audit establishes available auth modes, not production OAuth grants.
 
+Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
+implementation by `auth` and its key connector is complete on its own. Follow
+the [provider auth migration](./provider-auth-migration.md#cloudflare) for
+Cloudflare; the Cloudflare lines below record the 0.29 transition only.
+
 All three providers now default to hosted MCP. `surface: "api"` explicitly
 selects a REST complement and accepts only its API-specific options. The old
 Vercel/Cloudflare API modes are no longer complete alternatives; Notion retains
@@ -27,6 +32,11 @@ connectors: [
 ]
 ```
 
+Notion has since moved to auth-selected implementations: `surface` is gone,
+and `auth: { type: "oauth" }` or `{ type: "token" }` selects hosted MCP or the
+REST connector. Upgrade with the
+[provider auth migration](./provider-auth-migration.md#notion); the rest of
+this paragraph records the 0.29 rules.
 Notion preserves headless/internal-integration capabilities. Add explicit
 `surface: "api"` to retain that identity and migrate old REST names to
 `integration_*`, for example `search` to `integration_search`, `create_page`
@@ -48,9 +58,11 @@ complement. Replace `update_r2_bucket` with `cloudflare_api_mutate` using
 `cf-r2-storage-class` set to `Standard` or `InfrequentAccess`. Omit the body;
 include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write.
 `execute` remains a write even when its program only calls GET.
-Trusted pools may execute writes; read-only pools use direct host-approved writes.
+Writable endpoints may run `execute`; `readOnly` endpoints refuse it.
 
-For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
+Vercel's `surface` and ownership rules were later replaced: `auth` now selects
+the implementation. See the [provider auth migration](./provider-auth-migration.md#vercel).
+The 0.29 Vercel guidance follows for history. For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
 domain listing/adding, deployment cancellation and file uploads to live MCP
 schemas, and keep the independently authorized REST complement for value-safe
 project environment variables (including `upsert: false` create-only writes), domain verification/removal and deployment
@@ -59,7 +71,7 @@ category. Raw hatches refuse all published REST counterparts, including project
 creation/update. Do not copy REST argument
 shapes into vendor tools, even when a tool name is unchanged.
 
-The per-provider tables map every removed name and explain retained API tools:
-[Notion](https://github.com/zackbart/connecta/blob/main/src/providers/notion/reconciliation.md),
-[Vercel](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/reconciliation.md), and
-[Cloudflare](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/reconciliation.md).
+Every provider's table is retired with `surface`; the provider auth migration
+maps their names ([Notion](./provider-auth-migration.md#notion),
+[Cloudflare](./provider-auth-migration.md#cloudflare),
+[Vercel](./provider-auth-migration.md#vercel)).

package/examples/worker/AGENTS.md

@@ -37,6 +37,11 @@ This repository is deployment configuration, not a copy of Connecta itself.
   Import it from `@zackbart/connecta/worker`; direct upstream
   `new DynamicWorkerExecutor()` construction throws at boot. Keep the
   `@cloudflare/codemode` optional peer installed.
+- Keep the required `readOnly` choice in `src/connecta.config.ts`; startup
+  fails without it. `true` omits write tools from search and describe and
+  refuses every write call; `false` lets them run with MCP host approval. Named
+  pools inherit it unless they set their own `readOnly`. Do not configure the
+  removed `trust`.
 - Keep credentials in Worker secrets. Never commit credential values, Access
   service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
 - All state lives in the one D1 database bound as `CONNECTA_DB`, through

package/examples/worker/README.md

@@ -316,8 +316,8 @@ Rolling back to 0.24.x then requires reauthorizing those OAuth connectors.
 
 The shipped Notion connector uses a deployment-owned static header and echo
 needs no secret. To exercise vault controls, declare a `credential` slot on an
-`api()` connector or use Notion's explicit `surface: "api"` integration
-interface, which declares its own slot.
+`api()` connector or use a Notion connector with `auth: { type: "token" }`,
+which declares its own slot.
 Authorized users manage that slot inside the connection. Configuring a vault
 does not create credentials or permissions by itself.
 

package/examples/worker/src/connecta.config.ts

@@ -69,6 +69,11 @@ export default defineConfig((env: Env) => {
   return {
     publicUrl: env.PUBLIC_URL,
     storage,
+    // Required: can /mcp write? false lets call_destructive_tool and programs
+    // write, with the MCP client approving; true leaves write tools out of
+    // search and describe and refuses every write call. Pools inherit it
+    // unless they set their own readOnly. Startup fails without it.
+    readOnly: false,
     // Required adapter owns each run's handles; direct upstream construction throws.
     executor: workerExecutor({ loader: env.LOADER }),
     // Access owns edge admission and proves human identity for MCP and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -157,6 +157,10 @@
       "types": "./dist/providers/vercel/index.d.ts",
       "import": "./dist/providers/vercel/index.js"
     },
+    "./providers/wispr-flow": {
+      "types": "./dist/providers/wispr-flow/index.d.ts",
+      "import": "./dist/providers/wispr-flow/index.js"
+    },
     "./ui": {
       "types": "./dist/ui.d.ts",
       "import": "./dist/ui.js"
@@ -227,7 +231,8 @@
     "eval:regrade": "tsx eval/regrade.ts",
     "eval:compare": "tsx eval/compare.ts",
     "format": "oxfmt --write .",
-    "format:check": "oxfmt --check ."
+    "format:check": "oxfmt --check .",
+    "providers:spec": "tsx scripts/generate-openapi.mjs"
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",

package/templates/node/AGENTS.md

@@ -5,10 +5,12 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Edit `src/connecta.config.ts` for connectors, authentication, storage, public
   URL, and optional modules. `src/index.ts` only starts it.
 - Keep `executor: quickJsExecutor()` for the prescribed six-tool code-first
-  surface. Root and named pools default to `trust: "read-only"`: programs
-  may read, and writes use `call_destructive_tool`. Explicit `trusted` pools
-  also permit program writes and annotate `execute_code` as a write. Approval
-  belongs to the MCP host. Do not configure the removed `execute.approval`.
+  surface. Keep the required `readOnly` choice in the config: `false` lets
+  `call_destructive_tool` and programs write and annotates `execute_code` as
+  a write; `true` omits write tools from search and describe and refuses every
+  write call. Named pools inherit it unless they set their own `readOnly`.
+  Approval belongs to the MCP host. Do not configure the removed `trust` or
+  `execute.approval`.
 - Keep credentials in environment variables or an external secret store.
   Never commit `.env`, `.connecta.sqlite` (and its `-wal`/`-shm` files),
   tokens, or credential values.

package/templates/node/README.md

@@ -125,8 +125,10 @@ stored machine token to inspect Connections. Sign in with Clerk for human
 connection management. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
-The page labels each tool as a read or write. Trusted programs may write;
-read-only pools use `call_destructive_tool`, with approval controlled by the host. For
+The page labels each tool as a read or write and each endpoint as writable or
+read-only. `src/connecta.config.ts` must set `readOnly`: a read-only endpoint
+refuses every write call and leaves write tools out of search, and the host
+controls approval on a writable one. For
 classified connection failures it offers a fixed repair prompt, and its
 endpoint section has client setup commands for `/mcp` and any pool available
 to the signed-in identity. Those commands contain no bearer token.
@@ -188,8 +190,8 @@ node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 Keep this key outside the database. Losing it makes saved values unreadable;
 upgrades must reuse it. The shipped `time` connector declares no credential
 slot. Add `credential: { label: "API token" }` to an `api()` connector and read
-it through `await ctx.credential?.get()`, or use Notion's explicit
-`surface: "api"` integration interface, which declares its own slot. Authorized humans manage the slot inside that
+it through `await ctx.credential?.get()`, or use a Notion
+connector with `auth: { type: "token" }`, which declares its own slot. Authorized humans manage the slot inside that
 connection on `/`; there is no separate Credentials tab.
 
 In 0.25.0, this vault also seals downstream OAuth tokens on their first read.

package/templates/node/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.30.0",
+    "@zackbart/connecta": "0.32.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/connecta.config.ts

@@ -68,6 +68,11 @@ export default defineConfig((env: Env) => {
   return {
     storage,
     publicUrl,
+    // Required: can /mcp write? false lets call_destructive_tool and programs
+    // write, with the MCP client approving; true leaves write tools out of
+    // search and describe and refuses every write call. Pools inherit it
+    // unless they set their own readOnly. Startup fails without it.
+    readOnly: false,
     // Required: model-written programs run in a bounded QuickJS child.
     executor: quickJsExecutor(),
     auth: clerk ? [clerk] : [],