@zackbart/connecta 0.30.0 → 0.31.0

package/documentation/architecture.md

@@ -646,7 +646,7 @@ only: an array or a class instance there is refused by path, unread. String
 maps (static `headers`, `api()`'s `authorizationParams` and
 `tokenRequestHeaders`) are copied the same way and each value must be a
 string. A discriminated union (`remoteMcp()`'s `auth.type`,
-a provider's `surface`) with a missing or unrecognized discriminant throws
+a provider's `auth.type`) with a missing or unrecognized discriminant throws
 with the valid values. Only plain data is copied. Connectors, modules,
 executors, storage, loggers, handlers, and schemas are opaque and never
 entered. An `api()` tool carries its handler, so it is checked in place (own
@@ -712,7 +712,7 @@ call. The [provider guide](https://github.com/zackbart/connecta/blob/main/src/pr
 value-read conventions.
 
 A maintained provider is one `defineProvider()` call (`src/provider.ts`): a
-name, title, kind (`"mcp"`, `"api"`, or `"composed"`), a maintained skill, an
+name, title, kind (`"mcp"`, `"api"`, `"composed"`, or `"dual"`), a maintained skill, an
 optional reviewed classification, a closed `options` shape declared with
 `optionsOf<O>()`, and a synchronous `create`. The root exports the option-shape
 combinators and `PROVIDER_COMMON` so provider authors use the same validation
@@ -728,12 +728,124 @@ live in their own folders. The eight hosted implementations, including the
 MCP branches of Notion, Vercel, and Cloudflare, use reviewed presets over
 `remoteMcp({ classify })`. The eleven API-only factories retain an internal
 adapter to the same definition and description-stamping path. GitHub composes hosted tools with a scope-enforced REST complement.
-Notion, Vercel and Cloudflare default to hosted MCP and select explicit REST
-complements with `surface: "api"`. Configure both under distinct connector ids
-with independent credentials when both are needed. Notion preserves its
-internal-integration identity under `integration_*` names; Vercel and Cloudflare
-retain documented REST gaps rather than duplicate hosted operations. See the
-[provider migration guide](./provider-migration-0.29.md).
+A `"dual"` provider lets `auth` select the implementation
+([decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)):
+`variants(["auth", "type"], …)` closes each case's options, and
+`byAuth()` in `src/providers/_shared/rest/dispatch.ts` sends OAuth to
+`hostedOAuth()` (`remoteMcp()`, OAuth only, the reviewed classification) and a
+key to Connecta's REST connector. Stripe, Notion, Cloudflare, and Vercel are dual; `auth` is required.
+The REST connector (`src/providers/_shared/rest/`) serves
+`<vendor>_api_search`, `_api_details`, `_api_read`, and `_api_write` over an
+`OperationIndex` that `npm run providers:spec` compiles offline from the
+provider's pinned `openapi.source.json` into `openapi.generated.ts`.
+Each call is matched to an operation and checked against its parameters before
+transport; `_api_read` admits GET and the vendor's reviewed read-only POSTs in
+its handler, since classification is per tool name. Vendors configure only a
+transport, failure mapper, scope, framing, cursor extraction, a reviewed
+value-safety table (required; see below), argument-dependent refusals, and an
+idempotency header, plus optional hooks: `path` (fill default ids before
+matching), `admit` (an awaited check in `callRest` every tool passes, such as
+Cloudflare's account and zone pin), `result` (unwrap a vendor envelope;
+redaction runs after it and before cursors and `select`), a reviewed
+request-header allowlist, text bodies, and index `slashParams` that admit an
+encoded `/` in a final key segment (`test/rest-connector.test.ts`).
+Large documents opt into generator options that drop restated operation ids
+and plain path parameters and cap one operation's details (`opBudget`).
+`check:providers-generated` checks each index header against its source record
+offline; `providers:check` reports a pin that differs from the live document.
+No maintained provider selects an implementation with `surface` any more. See
+the
+[provider auth migration](./provider-auth-migration.md). Notion's token
+connector keeps its `integration_*` projections and authoring helpers beside
+the generic REST tools.
+
+#### Value safety for REST vendors
+
+The bar ([decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)):
+no REST tool response, success or error, returns a credential that grants
+access to the vendor or a third party, or a stored secret value, unless a
+reviewed named tool exists to return it. The threat model is Infisical's
+above: an honest server, with secrets people type into free text out of
+scope. Field-by-field redaction over a whole vendor API does not converge, so
+every vendor ships one reviewed table through one mechanism
+(`src/providers/_shared/rest/value-safety.ts`):
+
+1. **Candidates from the pinned spec.** `scripts/value-safety.mjs` flags every
+   operation whose success response names or describes a credential, keyed
+   value, header, environment, or binding container, or whose path, id,
+   summary, or description names a secret family (tokens, secrets, keys,
+   signing, webhooks, drains, transfer, claim, and invite codes). It is the
+   union of the detectors Cloudflare and Vercel shipped first, and
+   deliberately over-inclusive. `providers:spec` writes
+   `value-safety.candidates.json` beside the index when the source record sets
+   `options.valueSafety` (vendor `operationWords`; Stripe's `expansions: false`
+   skips id-or-object expansions, which are their own operations' candidates),
+   stamped with the pinned digest, the detector format, and its options. The
+   file is test evidence and never ships.
+2. **One reviewed verdict per candidate**, in the vendor's `value-safety.ts`:
+   `refuse` (the generic tools refuse it before transport, naming the
+   operation and the reason), `redact` (reviewed field paths), or `safe`, each
+   with a reason. Paths are dot paths into the data a tool returns: a list on
+   the way is traversed, `[]` and `{}`/`*` address list items and map values,
+   `@keys` replaces secret map keys, `[?env]`, `[?credential]`, and
+   `[?header]` filter list items, `url:` sanitizes a URL, and `origin:` (or a
+   `#url` suffix) keeps only scheme and host. `keep` names reviewed metadata
+   the heuristic leaves (children are still checked). A vendor whose objects
+   repeat across operations (Stripe) reviews a field once in `fields`,
+   `redact` or `keep`, wherever it appears, and states `resources`: rules
+   keyed on the object's type discriminator (Stripe's `object`) that apply to
+   every such object wherever a response embeds it (an expansion, a list, an
+   event's `data.object` and its `previous_attributes`). A resource rule can
+   return a reviewed payer-facing URL verbatim only while a declarative guest
+   condition holds (deny by default: a Checkout page only when every field
+   that can bind the session to a Customer, an Account, or saved payment
+   methods is empty and the session only takes a payment) and withhold it
+   otherwise. `providers:spec` derives the binding fields from the pinned
+   schema, and the harness fails until the condition lists each one. Argument-dependent refusals (Stripe expansions,
+   Vercel `decrypt`) stay in the vendor's `refuse` hook.
+3. **Redaction on every success body**, in `callRest` after `result` and
+   before cursors and `select`, so named tools, HEAD data, and uploads pass
+   through it too: the operation's reviewed paths, then the key-name
+   heuristic as defense in depth. The heuristic is the union of the former
+   vendor engines: a credential word anywhere in a non-metadata name removes
+   the value whole, a credential suffix removes the strings below it,
+   labelled or typed secret records lose their value, environment containers
+   lose their values, header, cookie, and query rules lose theirs, external
+   destinations keep their origin, and every URL loses userinfo and
+   credential-named query parameters or fragments. Exemptions are never
+   shared; each vendor states its own.
+4. **Errors.** A reviewed operation, or an unreviewed one whose request
+   accepts a credential-named field, answers failures with the vendor's codes
+   and status but not its text, unless its verdict is wrapped in
+   `vendorErrors()` because a review found its errors cannot echo a stored
+   secret. Credentials Connecta sent are always removed by the sent-secrets
+   matcher.
+
+`providers:spec` (run under tsx) also checks the table against the pinned
+spec: every `redact` path and `keep` must name something the operation's
+response schema can return (through `options.valueSafety.dataRoot` for an
+envelope such as Cloudflare's `result`), and every resource rule path
+something the resource's schema can return. It stamps the paths that resolve
+into the candidates file and fails on the rest, unless
+`value-safety.absent.json` acknowledges them (shared verdicts applied to
+operations whose schema lacks a path, or fields a schema leaves undeclared;
+such paths still apply at runtime).
+
+`test/fixtures/value-safety.ts` is the shared harness each vendor's
+`value-safety.node.test.ts` runs; `reviewProblems` is pure, and
+`test/value-safety-harness.node.test.ts` proves wrong paths fail it. It fails
+on candidates from another pin, format, or option set; an unreviewed
+candidate; a verdict for an operation the index lacks; a table path the stamp
+lacks (unresolved, or edited since `providers:spec`); a flagged field no path,
+keep, field review, or scope map covers; a flagged field, built in the shape
+the pinned schema gives it, that survives redaction or that no redact path
+reaches; a keep that exempts anything below it or a vendor-wide keep of a
+credential name; a redact path or resource rule that leaves its value at the
+top level, in a list, an expansion, or an event; a refusal that reaches
+transport; a reviewed operation that echoes vendor error text; and a moved
+verdict count.
+`RestVendor.valueSafety` is required, so a new REST vendor cannot ship without
+a table.
 
 `remoteMcp({ classify })` is the public way to declare what a downstream's
 tools do: `{ tools: { name: "read" | "write" | "destructive" | { verdict,

package/documentation/integrating.md

@@ -49,11 +49,22 @@ mapping from admitted identity to the downstream account; a request must not
 choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
-Notion, Vercel, and Cloudflare default to hosted MCP. Their explicit
-`surface: "api"` choices retain selected REST capabilities, with Notion's
-internal-integration identity preserved. To use both, configure distinct IDs
-and independent credentials. Read the [0.29 migration guide](./provider-migration-0.29.md)
-and its provider reconciliation tables for retained and removed names.
+Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
+server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
+with an operator-managed key. Notion requires `auth` the same way:
+`{ type: "oauth" }` acts as the signed-in user over Notion's hosted MCP, and
+`{ type: "token" }` acts as an internal integration over Connecta's REST
+connector. Cloudflare requires `auth` too: `{ type: "oauth" }` reaches its
+hosted MCP server, and `{ type: "apiToken" }` or `{ type: "globalApiKey" }`
+reaches Connecta's REST connector, with an optional `pin` of accounts and zones
+(required for a Global API Key unless `unpinned: true`). Vercel requires `auth`
+as well: `{ type: "oauth" }` reaches Vercel's hosted MCP server, and
+`{ type: "token" }` with an optional `teamId` reaches Connecta's REST connector
+with an operator-managed access token. Vercel admits only reviewed and approved
+MCP clients to its hosted server, an operational gate outside Connecta. See the
+[provider auth migration](./provider-auth-migration.md).
+To use both implementations of one provider, configure two connector ids with
+independent credentials.
 
 ## Another remote MCP server
 

package/documentation/meta-tools.md

@@ -924,8 +924,15 @@ scoped registry, including an empty list when none are accessible. They never
 list connectors from another pool or identity's grants.
 
 A write that times out after dispatch returns `write_outcome_unknown` with
-`retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted? }`.
-No write is automatically replayed. `args` may be partial reconciliation context
+`retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted?, recovery? }`.
+No write is automatically replayed. `recovery` carries facts the connector
+recorded before dispatch (`src/call-recovery.ts`), such as the `idempotencyKey`
+a REST connector generated; a deliberate retry that reuses it with the exact
+original arguments cannot repeat the write while the vendor retains the key
+(Stripe may prune v1 keys after 24 hours). After that, look the object up before
+retrying. When a connector recorded such facts, any other dispatched write whose
+outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
+with them under its own code, and trusted-program write accounting keeps it. `args` may be partial reconciliation context
 with `argsRedacted: true`. A withheld echo or arguments over the 512-byte budget
 carry `argsOmitted: true`; sensitive or unresolved schemas also carry
 `argsRedacted: true`. When `args` is absent or redacted, use the original

package/documentation/provider-auth-migration.md

@@ -0,0 +1,307 @@
+# 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 the pool trust
+policy gates 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 pools: hosted `execute` is always a write, even for a program that
+only reads, so a read-only pool 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`
@@ -50,7 +60,9 @@ 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.
 
-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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.30.0",
+  "version": "0.31.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.",
@@ -227,7 +227,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/README.md

@@ -188,8 +188,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.31.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {