@zackbart/connecta 0.28.0 → 0.28.1

package/dist/providers/vercel.js

@@ -9,7 +9,7 @@
  * those rows with Vercel's published OpenAPI document at
  * https://openapi.vercel.sh/ without needing a credential.
  */
-import { api, defined } from "../connectors/api.js";
+import { apiConnector as api, defined } from "../connectors/api-connector.js";
 import { remoteMcp } from "../connectors/remote-mcp.js";
 import { vettedCatalog, withVettedCatalog } from "../catalog-drift.js";
 import { guardedFetch, retryAfterMs, } from "../connectors/guarded-fetch.js";

package/dist/routes/oauth.js

@@ -102,6 +102,30 @@ export function routeOAuthCallback(context) {
         return Effect.succeed(null);
     return Effect.uninterruptible(Effect.promise(() => finishOAuthCallback(context)));
 }
+/**
+ * RFC 6749's error codes (sections 4.1.2.1 and 5.2) and RFC 8707's
+ * `invalid_target`. Only a code on this list is logged: the `code` an OAuth
+ * error carries is the provider's own text.
+ */
+const TOKEN_ERROR_CODES = new Set([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    "invalid_target",
+    "access_denied",
+    "server_error",
+    "temporarily_unavailable",
+]);
+/** ` with OAuth error <code>` for a known code; nothing for anything else. */
+function exchangeErrorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" && TOKEN_ERROR_CODES.has(code)
+        ? ` with OAuth error ${code}`
+        : "";
+}
 async function finishOAuthCallback(context) {
     const { path, url, baseUrl, opts } = context;
     const error = url.searchParams.get("error");
@@ -198,10 +222,12 @@ async function finishOAuthCallback(context) {
             return html("connected", opts, connector);
         }
         catch (err) {
-            // The page names the reason and nothing else; what the exchange threw can
-            // quote a token endpoint's body, so it goes only to the operator log.
+            // Neither the page nor the log repeats what the exchange threw: the SDK
+            // quotes the token endpoint's error_description or raw body, and a
+            // provider echoing a client_secret_post request puts the secret there.
             opts.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
-                `with 500: the authorization code exchange threw ${loggableValue(msg(err))}.`);
+                `with 500: the authorization code exchange failed${exchangeErrorCode(err)}. ` +
+                "Check the connector's client configuration and re-run authorization.");
             return html("exchange_failed", opts, connector);
         }
     }

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.28.0";
+export declare const CONNECTA_VERSION = "0.28.1";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.28.0";
+export const CONNECTA_VERSION = "0.28.1";

package/documentation/architecture.md

@@ -21,8 +21,10 @@ health, and the per-connector call limiters. It is built once and lives as long
 as the isolate — on Workers a lazy module-scope singleton, which is why both
 deployment shapes construct it outside the request handler.
 
-An OAuth `remoteMcp()` connector also owns a runtime-local refresh completion
-gate (`src/auth/downstream-oauth.ts`). It coordinates credential mutation across
+An OAuth connector — `remoteMcp()`, or `api()` with a static grant
+(`src/auth/static-oauth.ts`, the same provider with its discovery and client
+answered from config) — also owns a runtime-local refresh completion gate
+(`src/auth/downstream-oauth.ts`). It coordinates credential mutation across
 concurrent request scopes while sharing no client, transport, or response, and
 never lets a follower cancel the owner. The subtle part is that a valid token
 response consumes the refresh token whether or not the owner survives to save it,
@@ -627,7 +629,7 @@ src/
   skills.ts           MCP instructions, the usage skill, connector guides
   catalog-drift.ts    vetted manifests and the counts a refresh produces
   activity.ts         optional history factory and best-effort recorder
-  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth
+  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
   executors/          the QuickJS pool and child (Node only)
   node.ts             listen() + fileStorage re-export (Node only)
 ```

package/documentation/auth.md

@@ -305,7 +305,9 @@ or epoch does not open. Anything that fails to open — a tampered value, a
 rotated key — reads as absent: the connector reports `auth_required` and logs a
 warning. The flow bookkeeping stays plaintext: `state`, the pending URL,
 discovery metadata, and the generation. The callback route reads `state`
-directly, and none of it authenticates anything by itself.
+directly, and none of it authenticates anything by itself. An
+[`api()` OAuth connector](#downstream-oauth-on-api) seals its tokens and
+verifier the same way and stores no client at all.
 
 Plaintext left by an older release is read, then sealed where it lies through
 the same generation fence as any write, so an upgrade keeps the grant. Sealing
@@ -326,8 +328,8 @@ The operator's `POST /ui/oauth/<id>` takes a `mode` query parameter:
 
 | Request | What it does |
 | --- | --- |
-| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, the registered client, discovery, and any pending flow wiped, so the next flow registers a client again. |
-| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
+| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, discovery, and any pending flow wiped. A dynamically registered client may be carried into it ([below](#human-authentication-management)); one that is not carried is registered again. |
+| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes and still names the stored client; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
 | `DELETE /ui/oauth/<id>` | Disconnect: a disconnected epoch that passive reads never turn back into a consent flow. |
 
 Any other `mode`, or more than one, is a 400 before anything starts; the
@@ -592,9 +594,22 @@ the connector's URL, redirect URI, client metadata, auth scope, transport settin
 and owner partition still match. It drops the grant and one-shot flow state,
 selects the authorization server again, and re-seals the retained client under
 the replacement epoch key. A different issuer registers a new client. Disconnect
-and issuer-mismatch recovery discard it. The SDK has no client-validation
-exchange while constructing a fresh consent URL; a provider that revokes a
-retained client may refuse it only at consent or callback, after this request.
+and issuer-mismatch recovery discard it. A URL-based client is never carried:
+nothing was registered, and leaving it behind lets fresh metadata decide
+whether the server still accepts one. Neither is a client whose secret has
+expired.
+
+A carried client has to earn its next carry. Building a consent URL sends the
+provider nothing, so a restart cannot learn there that a provider has purged
+the client, and RFC 6749 forbids the provider from redirecting an unknown
+client back to the callback, so nothing arrives later either. Tokens in the
+epoch are the only proof the provider still knows it. A restart that follows
+a restart with no grant in between therefore registers again: a purged
+registration costs one refused consent, not a Restart that can never recover.
+A refusal connecta does hear is handled where it lands. A start whose refresh
+draws `invalid_client` drops the client and registers in that same start; a
+callback whose code exchange draws it drops the client, and Continue will not
+hand back the URL that named it.
 
 Credential and OAuth mutation require an admitted interactive human, connector
 visibility, the appropriate shared or personal permission, and an exact
@@ -636,8 +651,107 @@ existing dynamic registration flow. State validation, PKCE, issuer binding,
 encrypted token storage, refresh, and disconnect follow the same code paths.
 The metadata URL and scopes participate in the saved-client configuration
 binding, so restarting after either changes cannot reuse an old registration.
+A restart never carries the URL-based client itself, so a server that stops
+advertising support gets a registered client on the next restart.
 
 `scope` supplies space-separated default OAuth scopes through client metadata.
 A downstream challenge or protected-resource scope declaration takes precedence,
 and the SDK adds `offline_access` when advertised for refresh-token grants.
 Omitting both settings preserves the existing discovery and registration flow.
+
+## Downstream OAuth on `api()`
+
+Some APIs a deployment needs have no MCP server and take nothing but OAuth.
+Church Community Builder's REST API accepts only a three-legged grant, issues
+its clients by hand, and publishes no metadata to discover. `api()` takes a
+static authorization-code configuration for that shape:
+
+```ts
+api("church", {
+  authScope: "personal",
+  oauth: {
+    authorizationEndpoint: "https://login.example.com/oauth/authorize",
+    tokenEndpoint: "https://api.example.com/oauth/token",
+    clientId: env.CHURCH_CLIENT_ID,
+    clientSecret: env.CHURCH_CLIENT_SECRET,
+    scope: "people:read",
+    apiOrigins: ["https://api.example.com"],
+  },
+  tools: [{
+    name: "get_person",
+    description: "Read one person",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+    handler: async ({ id }, ctx) => {
+      const response = await ctx.oauth!.fetch(
+        `https://api.example.com/people/${encodeURIComponent(id)}`,
+      );
+      return response.json();
+    },
+  }],
+});
+```
+
+Nothing is discovered, registered, or learned. Every URL is configuration, so
+the rule for [URLs a downstream advertises](#urls-a-downstream-advertises)
+has nothing to check, and the endpoints are checked once, at construction:
+HTTPS (HTTP only on loopback), no credentials, no fragment. PKCE with S256 is
+on unless `pkce: false`, which drops the challenge from the consent URL and
+the verifier from the exchange, for a server that refuses them.
+`authorizationParams` adds provider parameters but cannot restate the grant's
+own, and `tokenRequestHeaders` adds headers to the code exchange and every
+refresh — CCB's token endpoint wants its own `Accept` media type — but cannot
+set `Authorization`, `Content-Type`, `Content-Length`, `Cookie`, or `Host`. `tokenEndpointAuthMethod` defaults to `client_secret_basic` with a secret
+and `none` without; the mismatched pairings refuse to boot. A static server has
+no advertised issuer, so no RFC 9207 `iss` is demanded and no RFC 8707
+`resource` is sent. The grant is bound to the token endpoint instead:
+repointing it fences the old tokens behind a new epoch rather than sending
+them to the new server.
+
+**The client lives in deployment configuration, not a vault slot.** It is the
+deployment's identity at the provider — one per deployment, like Clerk's
+`secretKey` — while a vault slot belongs to an owner: on a personal connector
+every human would paste the deployment's secret into their own partition.
+Configuration also keeps it out of storage altogether. It is never written,
+sealed or otherwise, so a leaked store holds no client secret, Disconnect has
+nothing of it to delete, and Restart has no registration to carry forward.
+Read it from the environment or a Worker secret; an empty string, the usual
+unset variable, refuses to boot without quoting it.
+
+Handlers never see the grant. `ctx.oauth.fetch(url, init)` sends the calling
+owner's access token as `Authorization: Bearer` and does four things a
+hand-rolled header would not:
+
+- **It sends the token to `apiOrigins` and nowhere else.** A request to any
+  other origin is refused before it leaves, so an untrusted URL in a response
+  — a pagination link, a webhook target — cannot carry the token off.
+  Redirects come back unfollowed, and a handler cannot set `Authorization`
+  itself.
+- **A 401 earns exactly one recovery.** If another request has already
+  rotated a token in, that token is used; otherwise one refresh runs through
+  the same coordinator as `remoteMcp()`, coalesced across requests, with the
+  rotating refresh token persisted even if its owner is cancelled after the
+  answer arrives. The request is then replayed once, which is why a stream
+  body is refused.
+- **Failures land in the existing classes.** No grant, a second 401, or a
+  [dead refresh](#refresh-failures), whose refused tokens are deleted on the
+  spot, is `auth_required` and routes the agent to `authorize_connector`. An
+  authorization-server outage is a retryable `unavailable` that keeps the
+  grant. A second 401 is latched for the rest of the request scope, so a
+  program's next fifty calls do not spend fifty refreshes on it.
+- **It reads and writes nothing a handler can name.** Storage, sealing, and the
+  owner partition are the registry's, exactly as for `remoteMcp()`.
+
+Everything else is the `remoteMcp()` grant, unchanged: the epoch fence and its
+cleanup lineage, sealing under the vault key, shared and personal ownership,
+the callback route and its state and principal checks, `authorize_connector`,
+and the operator's Connect, Restart, and Disconnect. Status reports a stored
+grant as healthy without asking the downstream — failing at use is enough —
+and never starts authorization. One difference is deliberate: the first start
+publishes a modern epoch at once. The legacy generation exists so a grant from
+before epochs survives an upgrade, and an `api()` grant has no such past.
+
+`oauth` and `credential` are exclusive on one connector, so `auth_required`
+names one recovery. A provider that offers both a personal access token and
+OAuth, as Planning Center does, lets the deployment choose which to pass;
+handlers branch on whether `ctx.oauth` is present.

package/ethos.md

@@ -33,12 +33,13 @@ carries them.
 | --- | --- | --- |
 | OpenAPI / GraphQL ingestion | refused | the disease is a document-authored tool nobody chose; hand-written literals, even through a shared factory, are still authorship |
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
-| Approvals and pauses | removed | hosts approve per call, so under always-allow the resume prompt was a rubber stamp that cost a round trip and a replay; programs stay read-only and each write is its own `call_destructive_tool` ([#672](https://github.com/zackbart/connecta/issues/672), superseding [#565](https://github.com/zackbart/connecta/issues/565)) |
+| Approvals and pauses | removed | hosts approve per call, so under always-allow the resume prompt was a rubber stamp that cost a round trip and a replay ([#672](https://github.com/zackbart/connecta/issues/672), superseding [#565](https://github.com/zackbart/connecta/issues/565)) |
 | Approval exemptions | accepted | config-only, program-only, never read-only elsewhere ([#566](https://github.com/zackbart/connecta/issues/566)) |
 | Runtime connector registration | refused | config-as-code is the security model |
 | Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
 | Artifacts module | accepted | a built-in connector for team-only sandboxed pages over stored JSON; immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) |
 | Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| OAuth on `api()` | accepted | OAuth-only APIs; static grants reuse `remoteMcp()` machinery, core's callback route |
 | Connecta-issued access tokens | accepted | optional /auth/access-tokens preserves v0.23 secrets; config owns grants, interactive management needs explicit permission ([#619](https://github.com/zackbart/connecta/issues/619)) |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
 | Resources, prompts, and downstream MCP Apps templates | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
@@ -72,8 +73,7 @@ carries them.
 
 ## Invariants
 
-Tests beside subsystem documentation enforce these; breaking one requires a
-design decision.
+Tests beside subsystem documentation enforce these.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "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 seven meta-tools.",
@@ -67,6 +67,14 @@
       "types": "./dist/auth/cloudflare-access.d.ts",
       "import": "./dist/auth/cloudflare-access.js"
     },
+    "./providers/breeze": {
+      "types": "./dist/providers/breeze.d.ts",
+      "import": "./dist/providers/breeze.js"
+    },
+    "./providers/basecamp": {
+      "types": "./dist/providers/basecamp.d.ts",
+      "import": "./dist/providers/basecamp.js"
+    },
     "./providers/cloudflare": {
       "types": "./dist/providers/cloudflare.d.ts",
       "import": "./dist/providers/cloudflare.js"
@@ -95,6 +103,22 @@
       "types": "./dist/providers/vercel.d.ts",
       "import": "./dist/providers/vercel.js"
     },
+    "./providers/ccb": {
+      "types": "./dist/providers/ccb.d.ts",
+      "import": "./dist/providers/ccb.js"
+    },
+    "./providers/planning-center": {
+      "types": "./dist/providers/planning-center.d.ts",
+      "import": "./dist/providers/planning-center.js"
+    },
+    "./providers/overflow": {
+      "types": "./dist/providers/overflow.d.ts",
+      "import": "./dist/providers/overflow.js"
+    },
+    "./providers/tithely": {
+      "types": "./dist/providers/tithely.d.ts",
+      "import": "./dist/providers/tithely.js"
+    },
     "./ui": {
       "types": "./dist/ui.d.ts",
       "import": "./dist/ui.js"

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.28.0",
+    "@zackbart/connecta": "0.28.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {