@zackbart/connecta 0.30.0 → 0.32.0

package/dist/routes/mcp.js

@@ -294,7 +294,7 @@ function toolkitRetired(logger, sentSecrets) {
         },
     });
 }
-function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, registry, canManageAuth, principalKey, runtimeContext, trust = "read-only", pool, principalActor) {
+function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, registry, canManageAuth, principalKey, runtimeContext, readOnly = false, pool, principalActor) {
     const sentSecrets = sentSecretsForRequest(requestScope);
     // Every McpServer the request builds is fresh and closes with its scope.
     // The modern handler tears its own down after the exchange; the legacy
@@ -361,7 +361,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             client,
             baseUrl,
             requestScope,
-            trust,
+            readOnly,
             canManageAuth,
             oauthConnectUrl: (id, force) => oauthConnectUrl(opts, baseUrl, id, principalKey, force),
             oauthConnectUnavailable: oauthConnectUnavailable(opts),
@@ -385,7 +385,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             requestSignal,
             ...(runtimeContext?.waitUntil ? { defer: runtimeContext.waitUntil.bind(runtimeContext) } : {}),
             ...executeLimits(opts.config),
-            trust,
+            readOnly,
         });
         servers.push(server);
         return server;
@@ -517,6 +517,8 @@ export function createMcpRoute(opts) {
     };
     function routeMcp(context) {
         const { path, request, baseUrl, runtimeContext } = context;
+        // Protected-resource metadata stays public, including when a grant is
+        // configured, so a fresh OAuth client can discover how to authenticate.
         if (path !== "/mcp" && !path.startsWith("/mcp/"))
             return Effect.succeed(null);
         // Admission, refusal bodies, SDK serialization and connector work share
@@ -644,7 +646,23 @@ export function createMcpRoute(opts) {
                 // one identical 404 so a credential never enumerates the other pools;
                 // the operator log is where the reason lives.
                 let access = authz;
-                let trust = opts.config.trust;
+                let readOnly = opts.config.readOnly;
+                if (poolName === undefined && opts.config.grant) {
+                    const denialReason = yield* Effect.promise(async () => {
+                        try {
+                            return (await opts.config.grant(authz.identity)) === true
+                                ? undefined
+                                : "default_grant_denied";
+                        }
+                        catch {
+                            return "default_grant_threw";
+                        }
+                    });
+                    if (denialReason !== undefined) {
+                        logFailure(opts.config.logger, "MCP default endpoint request denied", failureRecord({ reason: denialReason }));
+                        return cors(mcpRefusal(sentSecrets, 404, -33004, "MCP endpoint not found."));
+                    }
+                }
                 if (poolName !== undefined) {
                     const pool = opts.pools?.get(poolName);
                     const denialReason = !pool
@@ -662,7 +680,7 @@ export function createMcpRoute(opts) {
                         return cors(mcpRefusal(sentSecrets, 404, -33004, "MCP endpoint not found."));
                     }
                     access = intersectAccess(authz, pool.access);
-                    trust = pool.trust;
+                    readOnly = pool.readOnly;
                 }
                 let scopedRegistry;
                 try {
@@ -685,21 +703,23 @@ export function createMcpRoute(opts) {
                             if (current.subjectKey !== authz.subjectKey || current.principalKey !== authz.principalKey)
                                 return false;
                             validateAuthPermissions(current, opts.registry);
+                            if (poolName === undefined && opts.config.grant && (await opts.config.grant(current.identity)) !== true)
+                                return false;
                             let currentAccess = current;
-                            let currentTrust = opts.config.trust;
+                            let currentReadOnly = opts.config.readOnly;
                             if (poolName !== undefined) {
                                 const pool = opts.pools.get(poolName);
                                 if (!pool || (await pool.grant(current.identity)) !== true)
                                     return false;
                                 currentAccess = intersectAccess(current, pool.access);
-                                currentTrust = pool.trust;
+                                currentReadOnly = pool.readOnly;
                             }
                             const view = opts.registry.scoped({
                                 ...currentAccess,
                                 ...(current.subjectKey ? { subjectKey: current.subjectKey } : {}),
                                 ...(current.principalKey ? { principalKey: current.principalKey } : {}),
                             });
-                            if (classification === "write" && currentTrust !== "trusted")
+                            if (classification === "write" && currentReadOnly)
                                 return false;
                             if (address === undefined)
                                 return true;
@@ -716,7 +736,7 @@ export function createMcpRoute(opts) {
                                 return Boolean(tool &&
                                     (access === "catalog" ||
                                         (classification === "read" && tool.classification === "read") ||
-                                        currentTrust === "trusted"));
+                                        !currentReadOnly));
                             }
                             finally {
                                 await closeConnectorScope(resolved.connector, view.contextFor(resolved.connector.id, baseUrl, requestScope), runtimeContext?.waitUntil?.bind(runtimeContext));
@@ -740,7 +760,7 @@ export function createMcpRoute(opts) {
                 return cors(yield* serveMcp(localRequest, localAbort.signal, requestScope, opts, baseUrl, authz.actor, scopedRegistry, (id) => {
                     const connector = scopedRegistry.getConnector(id);
                     return Boolean(connector && mayManageConnector(authz, connector));
-                }, authz.principalKey, runtimeContext, trust, poolName, authz.identity.principal
+                }, authz.principalKey, runtimeContext, readOnly, poolName, authz.identity.principal
                     ? {
                         kind: authz.actor.kind,
                         id: authz.identity.principal.id,

package/dist/routes/operator.js

@@ -62,13 +62,20 @@ export function scopeFor(authz, connectorIds = authz.connectorIds) {
  * included, rather than quietly granting what remains.
  */
 export function visibleRegistry({ opts }, authz) {
-    return Effect.try({
-        try: () => {
-            validateAuthPermissions(authz, opts.registry);
-            return opts.registry.scoped(scopeFor(authz));
-        },
-        catch: (error) => new Answer(privateJson({ error: msg(error) }, { status: 403 })),
-    });
+    // Operator catalogs describe the default endpoint's view, never a pool view.
+    // Authentication alone cannot admit a caller that deployment code refuses.
+    const admission = opts.config.grant
+        ? Effect.tryPromise(async () => (await opts.config.grant(authz.identity)) === true).pipe(Effect.orElseSucceed(() => false))
+        : Effect.succeed(true);
+    return Effect.flatMap(admission, (allowed) => allowed
+        ? Effect.try({
+            try: () => {
+                validateAuthPermissions(authz, opts.registry);
+                return opts.registry.scoped(scopeFor(authz));
+            },
+            catch: (error) => new Answer(privateJson({ error: msg(error) }, { status: 403 })),
+        })
+        : refuse("not found", 404));
 }
 /**
  * Run one route program to its Response.

package/dist/routes/ui-config.js

@@ -154,7 +154,7 @@ function configRead(context) {
                 pools.push({
                     name,
                     path: `/mcp/${name}`,
-                    trust: pool.trust,
+                    readOnly: pool.readOnly,
                     grants: grants(intersectAccess(authz, pool.access), ids),
                 });
         }
@@ -199,7 +199,7 @@ function configRead(context) {
             you: {
                 interactive: authz.identity.interactive,
                 grants: grants(authz, ids),
-                trust: opts.config.trust,
+                readOnly: opts.config.readOnly,
                 pools,
                 permissions: {
                     activity: activity === "available" || activity === "unavailable",

package/dist/server.js

@@ -88,6 +88,9 @@ export function createFetchHandler(opts) {
             });
         }
         if (path.startsWith("/.well-known/")) {
+            const guardedMetadata = yield* routeMcp.handle(context);
+            if (guardedMetadata)
+                return guardedMetadata;
             const response = yield* metadata(request, baseUrl);
             if (response)
                 return response;

package/dist/skills.js

@@ -7,11 +7,12 @@ import { sentSecretsForRequest } from "./sent-secrets.js";
 const ROUTE = "Choose a route before discovery. One known-address read uses call_tool; one known-address write uses call_destructive_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.";
 const RECOVERY = 'When an auth error includes a handoff, give it to the user or operator. Use authorize_connector for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Fetch skills({ name: "usage" }) only for missing guidance or program repair.';
 /**
- * The always-loaded MCP `instructions` string. A program runs reads and the
- * writes in trusted pools; a read-only pool routes every write to top-level
- * call_destructive_tool, where the host's permission prompt is the approval.
+ * The always-loaded MCP `instructions` string. An endpoint is writable or
+ * read-only: a writable one lets programs and call_destructive_tool write,
+ * and the client owns approval; a read-only one omits write tools from search
+ * and describe and refuses every write call. Guides may still name them.
  */
-export const CONNECTA_INSTRUCTIONS = `${ROUTE} Programs call reads in read-only pools and may also write in trusted pools. The execute_code description names this endpoint's trust. In a read-only pool, discover writes with search_tools then use call_destructive_tool. Never repeat a write to recover its output. ${RECOVERY}`;
+export const CONNECTA_INSTRUCTIONS = `${ROUTE} On a writable endpoint, programs and call_destructive_tool may write. On a read-only endpoint, search omits write tools and every write call is refused; guides may still name them. The execute_code description says which this endpoint is. Never repeat a write to recover its output. ${RECOVERY}`;
 export { USAGE_SKILL } from "./usage-guide.js";
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {

package/dist/tool-safety.js

@@ -14,9 +14,17 @@ export function classifyTool(definition, override, review) {
         ? "read"
         : "write";
 }
-/** The only permission decision for a connector call. Approval is host-owned. */
-export function surfaceAllowsTool(classification, surface, trust = "read-only") {
-    return (classification === "read" ||
-        surface === "call_destructive_tool" ||
-        (surface === "execute_code" && trust === "trusted"));
+/**
+ * The only permission decision for a connector call. Approval is client-owned.
+ * A read-only endpoint refuses every write on every surface; a writable one
+ * sends writes through call_destructive_tool and programs, never call_tool.
+ */
+export function writeRefusal(classification, surface, readOnly = false) {
+    if (classification === "read")
+        return undefined;
+    if (readOnly)
+        return "read_only_endpoint";
+    return surface === "call_destructive_tool" || surface === "execute_code"
+        ? undefined
+        : "destructive_tool_requires_approval";
 }

package/dist/types.d.ts

@@ -95,7 +95,7 @@ export interface ToolDef {
      * Standard MCP tool behavior hints plus provider-specific extensions.
      * The registry classifies these after deployment overrides and provider
      * review. Only a stored read verdict may use call_tool; program writes
-     * require a trusted pool. Approval belongs to the host.
+     * require a writable endpoint. Approval belongs to the host.
      */
     annotations?: ToolAnnotations;
 }

package/dist/ui.d.ts

@@ -9,7 +9,7 @@ export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, i
 export type OperatorPage = import("./operator-ui/view.js").OperatorPage;
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
-/** Report the verdict the registry stored, independent of pool trust. */
+/** Report the verdict the registry stored, independent of whether an endpoint is read-only. */
 export declare function uiToolSafety(definition: ToolDef): UiToolSafety;
 /**
  * The fix-prompt key for a connector that is not usable. Chosen from the

package/dist/ui.js

@@ -40,7 +40,7 @@ export function operatorPageForPath(path) {
 export function operatorPageTitle(page, configuredTitle) {
     return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
 }
-/** Report the verdict the registry stored, independent of pool trust. */
+/** Report the verdict the registry stored, independent of whether an endpoint is read-only. */
 export function uiToolSafety(definition) {
     if (definition.classification === "read")
         return "runs_in_programs";

package/dist/usage-guide.js

@@ -16,9 +16,9 @@ description: How to route work between one execute_code program and Connecta's e
 
 Read one account with call_tool: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
 Discover and call together when schemas suffice. search_tools covers catalog
-inspection and write discovery in read-only pools. Programs may
-write only in trusted pools; the tool description states this endpoint's trust.
-Unannotated tools fail closed to writes.
+inspection. On a read-only endpoint, as execute_code's description says, search
+omits writes (guides may name them) and each fails read_only_endpoint; tell the
+user. Unannotated tools fail closed to writes.
 
 ## The global and the envelopes
 

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.30.0";
+export declare const CONNECTA_VERSION = "0.32.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.30.0";
+export const CONNECTA_VERSION = "0.32.0";

package/dist/write-outcome.js

@@ -0,0 +1,47 @@
+/**
+ * Whether a write landed, as far as anyone can know.
+ *
+ * `unknown` is the outcome a result must never paper over: the call left
+ * connecta and no answer came back, so sending it again could do it twice and
+ * not sending it could leave it undone. That is a dispatched call that timed
+ * out, was cancelled, found the service unavailable, or failed any way that
+ * is not a verdict. A refusal code (`REFUSALS`) or a downstream tool's own
+ * `isError` is an answer, so it is `failed`. Response text does not decide
+ * whether an outcome is unknown. A call that was never dispatched is
+ * `failed`: nothing was sent.
+ * `result_processing_failed` means the downstream call completed.
+ */
+export function classifyWriteOutcome(outcome) {
+    if (outcome.ok)
+        return "ok";
+    if (!outcome.dispatched)
+        return "failed";
+    const code = outcome.error?.code;
+    if (code === "result_processing_failed")
+        return "ok";
+    if (code === "timeout" || code === "cancelled" || code === "unavailable") {
+        return "unknown";
+    }
+    if (code !== undefined && REFUSALS.has(code))
+        return "failed";
+    return outcome.answered === true ? "failed" : "unknown";
+}
+/**
+ * Codes that say the other side refused the call rather than acted on it:
+ * the credential, the arguments, the resource, the rate, or a base version
+ * someone else already moved past (`conflict`). Anything else a
+ * connector reports after dispatch — `connector_call_failed` from a response
+ * too large to read, a redirect it would not follow, a body it could not
+ * parse, a 5xx — may come after the write landed, so only a downstream
+ * tool's own `isError` answer makes it a known failure.
+ */
+const REFUSALS = new Set([
+    "auth_required",
+    "downstream_oauth_required",
+    "provider_permission_denied",
+    "invalid_args",
+    "not_found",
+    "rate_limited",
+    "input_required_unsupported",
+    "conflict",
+]);

package/documentation/README.md

@@ -22,6 +22,7 @@ service, or change Connecta itself.
 | [Operator UI](./operator-ui.md)                             | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
 | [Operator UI tests](./operator-tests.md)                    | Browser state matrix, real-server flows, and snapshot maintenance                                             |
 | [Provider migration for 0.29](./provider-migration-0.29.md) | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
+| [Provider auth migration](./provider-auth-migration.md)     | Upgrade actions when `auth` selects hosted MCP or Connecta's REST connector, Stripe and Vercel                |
 
 Each long contract starts with task routes. Follow those section links before
 reading the whole guide. Source and test pointers identify where to check a

package/documentation/architecture.md

@@ -85,20 +85,20 @@ table, security headers. Route _order_ is the contract — several routes would
 behave differently if they were reachable in another order — so read the table
 top to bottom.
 
-| Order | Route                                                     | Notes                                                                                                                                                                                                                                                              |
-| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                          |
-| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                             |
-| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                               |
-| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                           |
-| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                             |
-| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                          |
-| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                       |
-| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                       |
-| 3     | `/.well-known/*`                                          | Auth metadata, or 404.                                                                                                                                                                                                                                             |
-| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                       |
-| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing grant, and a throwing grant are one identical 404; see [pools](./auth.md#pools). |
-| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                  |
+| Order | Route                                                     | Notes                                                                                                                                                                                                                                                                                |
+| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                                            |
+| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                                               |
+| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                                                 |
+| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                                             |
+| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                                               |
+| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                                            |
+| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                                         |
+| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                                         |
+| 3     | `/.well-known/*`                                          | Public auth metadata, or 404. Protected-resource discovery does not authenticate callers or evaluate endpoint grants.                                                                                                                                                                |
+| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                                         |
+| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing endpoint grant, and a throwing endpoint grant are one identical 404; see [pools](./auth.md#pools). |
+| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                                    |
 
 Every response leaves through `withSecurityHeaders`. HTML uses one common
 security-header helper, including status and error pages. Operator shells
@@ -131,12 +131,17 @@ An admitted non-preflight `/mcp` request then takes five steps in
 3. **Narrow to the pool.** On `/mcp/<pool>`, look the name up, run its grant
    against the identity, then `intersectAccess` the pool with the identity's own
    access. A pool can never widen a view; anything else is a 404 naming no pool.
+   The endpoint's `readOnly` is the pool's own value, else the deployment's;
+   plain `/mcp` uses the deployment's. It travels to the meta-tools and the
+   program as one boolean that drops writes from `CatalogService` search and
+   describe and makes `writeRefusal` (`src/tool-safety.ts`) refuse every write
+   call. Guides and skills are not filtered.
 4. **Derive the registry view.** One `registry.scoped(...)` call with those
    connector ids, exact `connector.tool` addresses when the identity declares a
    narrower slice, and the subject and principal keys. Personal connectors use
    the principal partition and result paging the subject partition with principal,
    endpoint/pool, origin, connector, and tool bindings. Paging rechecks current
-   grants, pool membership, and trust; no caller parameter selects a partition (`test/identity-scope.test.ts`).
+   grants, pool membership, and the endpoint's `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
@@ -217,13 +222,15 @@ or hands out, and a change usually belongs in exactly one of them:
 | `src/invocation.ts`      | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record.                                                                         |
 | `src/catalog.ts`         | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows.                                                                                                                               |
 | `src/result-shapes.ts`   | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none.                                                                                              |
-| `src/program-writes.ts`  | Trusted-pool write accounting: write budgets, dispatch draining, and known or unknown outcomes.                                                                                                                                  |
+| `src/program-writes.ts`  | Program write accounting on writable endpoints: write budgets, dispatch draining, and known or unknown outcomes.                                                                                                                 |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same two
 services, `CatalogService` and `InvocationService`. That is the point: a
 program's `connecta.call` and a top-level `call_tool` reach
 `InvocationService.invoke` by different routes and get the same admission, the
-same credential resolution, and the same fail-closed read-only check.
+same credential resolution, and the same fail-closed read-only check: one
+`writeRefusal` decision per call, from the stored classification, the calling
+surface, and the endpoint's `readOnly`.
 `test/execute.test.ts` asserts the parity directly, because a sandbox path that
 quietly diverges is how generated code would mint a capability.
 
@@ -646,7 +653,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 +719,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
@@ -723,17 +730,137 @@ connection context `create` supplies, the maintained text, then deployment
 instructions, which append and never replace. `src/provider.ts` imports neither
 transport, so an `api()` provider gains no MCP client or Effect graph from it
 (`test/purity.node.test.ts`). The factory carries its `definition`, which build and
-check tools read instead of keeping provider lists. All twenty providers
-live in their own folders. The eight hosted implementations, including the
+check tools read instead of keeping provider lists. Providers
+live in their own folders. 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
+`remoteMcp({ classify })`. The migrated 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 selects one implementation at construction, usually through `auth`
+([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 require `auth`. Mixpanel is also dual,
+with explicit `via: "mcp" | "api"` and MCP as the unchanged default: service accounts
+reach both implementations, so auth cannot distinguish them. API mode requires
+operator-managed service-account credentials and never falls back to MCP.
+Mixpanel uses the same REST transport, operation matching and value-safety engine
+for a narrow reviewed subset. Its official contracts are YAML and app identity
+has no published response schema, so its guide and drift record carry explicit
+manual review evidence instead of claiming a machine-checkable JSON pin.
+
+The generic 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,