@zackbart/connecta 0.36.0 → 0.36.2

package/documentation/auth.md

@@ -14,7 +14,7 @@ credential contracts; use [deployment setup](./deploying.md) for runnable steps.
 | Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [Clerk Organizations](#one-clerk-instance-one-organization-per-deployment), [management](#human-authentication-management) |
 | Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                                                                                                  |
 | Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)                                                                           |
-| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens)                                                                          |
+| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens), [Google hosted MCP](#google-service-account-tokens-and-hosted-mcp)      |
 | Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                                                                                                   |
 
 [Credential recognition and admission](#credential-recognition-and-admission)
@@ -412,6 +412,11 @@ agent. Enabling `preview` lets code on any pushed preview branch act as the agen
 Treat the project's OIDC token as a bearer credential for all of this agent's
 pools. Its default audience, `https://vercel.com/<team-slug>`, is shared by every
 service accepting Vercel's default OIDC tokens; it is not specific to Connecta.
+Connecta accepts only that default audience. Vercel's custom-audience token
+exchange can produce a validly signed token for another service; Connecta
+refuses it. For example, a token exchanged for `https://tickets.example.com`
+cannot authenticate to `/agent/assistant`. Resolve the ordinary workload token
+with `getVercelOidcToken()` without an `audience` option.
 Anything holding the project's token can act as the agent:
 project code, builds (including build steps and dependency install scripts with
 access to `VERCEL_OIDC_TOKEN`), and services the project sends the token to,
@@ -2493,6 +2498,48 @@ stored static-client state and reselects the configured identity.
 Configured `scope` is a fallback; a downstream challenge or protected-resource
 declaration takes precedence, and the SDK adds `offline_access` when advertised.
 
+### Browser authorization parameters
+
+Set `auth.authorizationParams` on an OAuth `remoteMcp()` connector to add
+non-secret provider parameters to the browser consent URL. This works with
+pre-registered clients, CIMD, and DCR. For example:
+
+```ts
+remoteMcp("crm", {
+  url: "https://mcp.example/mcp",
+  auth: {
+    type: "oauth",
+    scope: "records.read",
+    authorizationParams: { access_type: "offline", prompt: "consent" },
+  },
+});
+```
+
+Each configured parameter occurs once, replacing any same-name value already
+on the authorization endpoint URL. These parameters are never added to token
+exchange, refresh, registration, revocation, metadata, or MCP requests.
+Descriptions expose parameter names only. Values are public configuration,
+visible in the consent URL and stored with it; never put secrets here.
+
+The map must be a plain string record with at most 32 entries. Names contain
+1–128 ASCII letters, digits, dots, underscores, or hyphens. Values must be
+nonempty (not whitespace-only), at most 2048 UTF-16 code units, and contain no
+ASCII control characters. Case-variant duplicate names are refused. The
+following names, including every case variant, fail construction with
+`ConfigError`: `response_type`, `response_mode`, `client_id`, `client_secret`,
+`redirect_uri`, `state`, `code_challenge`, `code_challenge_method`, `scope`,
+`resource`, `request`, and `request_uri`. Configure scopes through `auth.scope`.
+`response_mode` is reserved because Connecta accepts callbacks only as GET query
+parameters.
+
+For remote MCP, the map joins the stored client configuration binding, like
+scope and client identity. Adding, removing, or changing a parameter requires
+Restart or Disconnect and reconnect to obtain a grant with the new consent
+settings. The map does not rewrite existing grants or pending consent URLs;
+as with scope, reconfiguring it alone does not obtain a new grant. A DCR
+registration created under different parameters cannot be carried through
+Restart. Key order is irrelevant; an empty map and omission are equivalent.
+
 ## Downstream OAuth on `api()`
 
 `api()` takes a static authorization-code configuration for APIs without MCP
@@ -2527,7 +2574,7 @@ No discovery or registration occurs; all URLs are configuration, so the
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Endpoints                    | Checked at construction: HTTPS, HTTP only on loopback, no credentials or fragment.                                                                                                                                                                                                                                                                                                                                             |
 | `pkce`                       | S256 by default; `false` omits challenge and verifier.                                                                                                                                                                                                                                                                                                                                                                         |
-| `authorizationParams`        | Adds provider parameters; cannot restate the grant's own.                                                                                                                                                                                                                                                                                                                                                                      |
+| `authorizationParams`        | Browser-only string parameters. Exact names `response_type`, `client_id`, `redirect_uri`, `state`, `scope`, `code_challenge`, `code_challenge_method` and `resource` are refused; other names and string values are accepted as before. Remote MCP's [stricter rules](#browser-authorization-parameters) do not apply here.                                                                                                    |
 | `expectedCallbackParameters` | Optional `Readonly<Record<string, string>>` of fixed provider response values. Each configured parameter must occur exactly once with its exact decoded value, after pending-state verification and before issuer validation, flow claims, code exchange, or grant persistence. Missing, duplicate, or mismatched values refuse without exchanging a code or returning parameter values. Omission preserves existing behavior. |
 | `revocationEndpoint`         | Optional trusted HTTPS revocation URL (loopback HTTP allowed), without credentials, query or fragment. Disconnect removes the local grant before one bounded attempt using the configured client. Failure reports `oauth_revocation_failed`; a repeated Disconnect never retries.                                                                                                                                              |
 | `revocationRequestFormat`    | `"form"` by default; `"json"` sends JSON without `token_type_hint`. Requires `revocationEndpoint` when set.                                                                                                                                                                                                                                                                                                                    |
@@ -2580,6 +2627,15 @@ owner's access token as `Authorization: Bearer` with these rules:
 - The answer's `.text()` and `.json()`, clones' too, decode its bytes as UTF-8, so
   workerd never quotes a downstream's Content-Type in its own log.
 
+`api()` already supports `oauth.authorizationParams` through the same OAuth
+provider and browser-only injection. It keeps its existing, more permissive
+validation (see the `api()` option table), so existing configurations still
+construct. Use only GET query response modes with it. Its existing binding remains
+unchanged: the token endpoint identifies the grant; scope, client identity,
+and authorization parameters do not add a stored client configuration binding.
+Changing authorization parameters affects new consents; reconnect to obtain a
+grant with different consent settings.
+
 The grant record and consents, epoch fencing, vault sealing, shared/personal ownership,
 callback state/principal checks, `authorize_connector`, Connect, Restart, and
 Disconnect match `remoteMcp()`. Status calls report a stored grant for the
@@ -2598,6 +2654,14 @@ transport, are not stored or described, and a changed token replaces the client.
 This mode refuses cleartext non-loopback origins. Optional `auth.headers` carry
 static protocol/catalog controls and cannot set Authorization.
 
+A resolver may expose `token.invalidate(rejectedToken, ctx): Promise<void>` to
+remove a cached token after a downstream HTTP 401. The hook receives the exact
+token sent by that transport, so it must leave a newer cached token intact.
+Hook failures are withheld and preserve the original 401. Request auth never
+automatically repeats the operation or renews the grant inside the failed
+scope: authorization failure stays latched for that scope. A new request resolves
+the callback again. In particular, no dispatched write is replayed.
+
 The GitHub provider validates each tool's owner/repo and scope access before
 resolving an installation token. It creates one token-bound MCP client for that
 operation and closes it before returning. Completed installation/token caches
@@ -2608,6 +2672,134 @@ is retained across requests, and rejected writes are never replayed. An omitted
 `describe()` includes neither the key nor the minted tokens. The maintained
 provider skill explains App permissions and installation prerequisites.
 
+### Google service-account tokens and hosted MCP
+
+Import `googleServiceAccountToken` from `@zackbart/connecta/google` to connect a
+Google hosted MCP server using a service-account JSON key on Node or Workers.
+This optional subpath is outside the root import graph. Supply deployment secrets
+through the environment or platform secret store:
+
+```ts
+import { remoteMcp } from "@zackbart/connecta";
+import { googleServiceAccountToken } from "@zackbart/connecta/google";
+
+const warehouse = remoteMcp("warehouse", {
+  url: "https://bigquery.googleapis.com/mcp",
+  authScope: "shared",
+  auth: {
+    type: "request",
+    token: googleServiceAccountToken({
+      serviceAccount: env.GOOGLE_SERVICE_ACCOUNT_JSON,
+      scopes: ["https://www.googleapis.com/auth/bigquery"],
+    }),
+  },
+});
+
+const warehousePersonal = remoteMcp("warehouse_personal", {
+  url: "https://bigquery.googleapis.com/mcp",
+  authScope: "personal",
+  auth: {
+    type: "oauth",
+    scope: "https://www.googleapis.com/auth/bigquery",
+    authorizationParams: { access_type: "offline", prompt: "consent" },
+    client: {
+      issuer: "https://accounts.google.com",
+      clientId: env.GOOGLE_CLIENT_ID,
+      clientSecret: env.GOOGLE_CLIENT_SECRET,
+      tokenEndpointAuthMethod: "client_secret_post",
+    },
+  },
+});
+```
+
+`serviceAccount` accepts downloaded JSON text or
+`{ clientEmail, privateKey, clientId? }`; `privateKey` is a PKCS#8 RSA PEM of at
+least 2048 bits. `scopes` must be a non-empty array of HTTPS URLs without
+credentials, whitespace, or fragments. Unknown options fail construction with
+`ConfigError`. An optional fixed `subject: "alice@example.com"` requests
+Workspace domain-wide delegation and requires its admin grant. Omit `subject`
+for BigQuery: the signed assertion then has no `sub` and acts as the service
+account itself. See [Google's service-account grant documentation](https://developers.google.com/identity/protocols/oauth2/service-account).
+
+The helper signs RS256 JWT-bearer assertions and exchanges them at Google's fixed
+token endpoint. It keeps only bounded in-memory token entries, partitioned by
+account, key fingerprint, absent-or-present subject and scope set. Concurrent
+mints share a flight; tokens refresh with a one-minute margin. Keys, assertions
+and tokens are never logged, persisted or described. Bearer tokens use request
+auth's existing secret redaction. A 401 evicts only the rejected token; the next
+request mints again. The failed operation is never automatically repeated.
+
+#### Separate agent and people connections
+
+Grant the shared connection to agent pools (including pools used by Eve agents)
+and the personal connection to pools used by people. Add these entries to the
+existing deployment configuration, keeping its inbound auth, executor, vault and
+storage configuration:
+
+```ts
+connectors: [warehouse, warehousePersonal],
+agents: ["assistant"],
+pools: {
+  warehouse_agents: { tools: ["warehouse"], members: ["agent:assistant"] },
+  warehouse_people: { tools: ["warehouse_personal"], members: ["user_alice"] },
+},
+```
+
+Replace `user_alice` with Alice's admitted principal ID. Agents have no principal;
+`authScope: "personal"` connectors never appear for them, even if included in a
+pool's tools. The shared connection uses its fixed service account for every
+member; the personal connection uses each person's own encrypted OAuth grant.
+People connect through `authorize_connector` or their member page. Follow
+[Add a person](#add-a-person), [agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens)
+and [shared credential ownership](#connect-a-shared-credential) for admission and
+pool membership. The request-token connection gets its key from deployment
+configuration and does not need a credential-vault slot.
+
+#### Google-side setup
+
+1. Enable the BigQuery API in the Google Cloud project and confirm that the
+   BigQuery MCP service is available under the project's organization policies.
+   Google's current setup uses `https://bigquery.googleapis.com/mcp` and API
+   enablement; follow its current server setup if enablement requirements change.
+   Grant the service account MCP Tool User (`roles/mcp.toolUser`) and BigQuery
+   Job User (`roles/bigquery.jobUser`) on the project where queries run.
+   [BigQuery MCP setup and required roles](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp).
+2. Grant BigQuery Data Viewer (`roles/bigquery.dataViewer`) on the datasets the
+   service account may query. Dataset grants restrict data access separately
+   from project-level job execution. Grant further permissions only for the
+   operations you intend to expose; OAuth scopes do not replace IAM.
+   [BigQuery IAM roles and grant levels](https://docs.cloud.google.com/bigquery/docs/access-control).
+   Create a service-account JSON key and store it as
+   `GOOGLE_SERVICE_ACCOUNT_JSON` in the deployment secret store; the helper
+   does not use ADC, metadata-server credentials, or workload identity federation.
+   [Service-account key creation](https://docs.cloud.google.com/iam/docs/keys-create-delete).
+3. For the personal connection, configure Google Auth Platform branding,
+   audience and data access. Choose **Internal** for an application restricted to
+   people in your Workspace organization, using a project belonging to that
+   organization. Internal consent does not grant dataset access; each person
+   still needs the applicable IAM permissions.
+   [Configure consent and audience](https://developers.google.com/workspace/guides/configure-oauth-consent).
+4. Create a **Web application** OAuth client under Google Auth Platform → Clients.
+   Register the exact Connecta callback, for example
+   `https://connecta.example/oauth/callback/warehouse_personal`, using the
+   deployment's configured public origin. Store its client ID and secret as
+   deployment secrets. Google's hosted MCP servers do not support DCR or client
+   metadata documents, so configure the static `auth.client` shown above.
+   [Web OAuth client setup](https://docs.cloud.google.com/mcp/set-up-authentication-mcp-servers#web),
+   [Google MCP registration limitations](https://docs.cloud.google.com/mcp/authenticate-mcp#limitations).
+
+The pre-registered client path supports Google's exact issuer and
+`client_secret_post`; Google's [discovery document](https://accounts.google.com/.well-known/openid-configuration)
+advertises that method, PKCE S256, and `https://oauth2.googleapis.com/token`.
+The personal example requests `access_type=offline` to obtain a refresh token
+and `prompt=consent` to show consent again when reconnecting. See
+[Google's offline-access requirements](https://developers.google.com/identity/protocols/oauth2/web-server#offline).
+Connecta retains the stored refresh token when a successful refresh response
+omits `refresh_token`, allowing later refreshes with that same token. After
+adding these parameters to an existing connector, Disconnect and reconnect.
+Live Google consent and project-specific permissions still need verification
+against the operator's project.
+
 ## Contributor reference
 
 ### INV-5 output redaction limits
@@ -2698,8 +2890,10 @@ The encoding lattice is exactly this, and anything outside it is out of scope:
 
 [Decision 0007](https://github.com/zackbart/connecta/blob/main/decisions/0007-agent-pool-layout.md)
 explains the pool layout; [decision 0006](https://github.com/zackbart/connecta/blob/main/decisions/0006-pools-are-the-access-model.md)
-explains pools as the access model. `test/identity-scope.test.ts` checks identity
-boundaries, and `src/storage/keys.ts` owns credential key families.
+explains pools as the access model. `test/identity-write-journey.node.test.ts`
+checks real HTTP identity, pool and personal credential isolation;
+`test/identity-scope.test.ts` retains handoff, callback and admission-revocation
+fault probes. `src/storage/keys.ts` owns credential key families.
 
 Inbound adapters live in [src/auth](https://github.com/zackbart/connecta/tree/main/src/auth);
 [auth routes](https://github.com/zackbart/connecta/blob/main/src/routes/oauth.ts)

package/documentation/code-mode.md

@@ -1274,7 +1274,7 @@ rejection, and branded adapter acceptance across module copies.
 | `S9`                   | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation)                                                                                                                                                                                                                                                                      |
 | `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                                                                              |
 | `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                                                                             |
-| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/program-writes.test.ts` (the refusal's `nextAction`, nothing sent, a caught refusal)                                                                                                                                                                                                                                                                                                                                    |
+| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                                                                                 |
 | `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                            |
 | `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                              |
 | `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -1288,10 +1288,10 @@ rejection, and branded adapter acceptance across module copies.
 | `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
 | `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
 | `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
-| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/d1-storage.node.test.ts` (shared stash transfers), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                        |
-| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/operator-view.test.ts`, `test/sql-storage-contract.ts`, run by `test/d1-storage.node.test.ts` and `test/sqlite-storage.node.test.ts` (historical pause and approval rows still render and round-trip)                              |
-| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited program write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                     |
-| `W10`, `W12`           | `test/program-writes.test.ts` (a writable endpoint's program write runs, a read-only endpoint omits writes from search and describe and refuses every write call on every path, including a write its guide names, a required deployment `readOnly`, the write budget, `readOnly` inheritance and overrides, `call_tool` still refusing, search and describe verdicts, construction refusals including retired `trust`), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                       |
+| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/kv-to-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                 |
+| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip)                                                             |
+| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                 |
+| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                           |
 | `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                   |
 | `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
 | `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |
@@ -1304,4 +1304,4 @@ rejection, and branded adapter acceptance across module copies.
 
 The surface itself is checked by `test/server.test.ts` (the exact six-tool list),
 `test/code-first-surface.test.ts` (construction, executor, removed tools, copy, and size),
-and `test/program-writes.test.ts` (the retired pause options refused at construction).
+and `test/program-writes.test.ts` (deployment policy and classification construction refusals).

package/documentation/meta-tools.md

@@ -1334,8 +1334,11 @@ Connector ids already appear in native tool names. The
 operator UI and `describeConfig()` show every pool's effective `surface` and
 `executeCode` as facts from deployment code. Change these settings in code.
 
-Keep native pools bounded. Comparisons so far used 40 synthetic tools;
-large production catalogs near the cap have not been evaluated.
+Keep native pools bounded. Local real-Eve validation uses seeded catalogs from
+40 through 1,000 downstream tools across meta, native and native-plus-code
+surfaces, with a deterministic model transport and no paid model calls. These
+checks establish local runtime contracts; model task quality and large
+production catalogs near the cap remain unmeasured.
 
 ### Eve agents
 

package/documentation/operator-tests.md

@@ -190,8 +190,17 @@ OAuth provider validates the code exchange and PKCE. Credential Test calls a
 loopback downstream endpoint. Operator APIs, cookie/bearer admission, CSRF,
 assets, handoffs, callbacks, and encrypted storage use production code.
 
-The flows cover Clerk sign-in/reload/sign-out; OAuth connect/consent/callback/
-connected reread/reload; and credential save/test/replace/remove. They collect
+The flows use a real SQLite file and cover Clerk sign-in/reload/sign-out,
+actual Settings provenance and asset cache validators; OAuth
+connect/consent/callback/connected reread/disconnect; and credential
+save/test/replace/remove. They close and reopen the app, database and vault
+before rereading OAuth and credential state. A rejected SQL replacement leaves
+the previous secret usable downstream after restart. Trigger rows read from an
+independent SQL connection require one save, one replacement and one removal;
+reads and the rejected save commit no credential writes. Actual MCP calls
+check that credential edits preserve a reader pool's read access and refusal. Activity renders
+successful calls recorded before the SQLite restart without exposing either
+credential value. They collect
 CSP violations across every document and popup, and fail on unexpected network
 traffic. No credentials enter visual fixtures or screenshot baselines.
 

package/documentation/operator-ui.md

@@ -644,8 +644,7 @@ and each personal connector's exact `manage`;
 The Overview's map and attention rows are pure functions of the contract in
 [connection-map.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/connection-map.ts)
 and [overview.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/overview.ts),
-covered by `test/operator-connection-map.test.ts` and
-`test/operator-overview.test.ts`; `src/operator-ui/styles/overview.css` holds
+exercised in Chromium by `test/browser/operator-overview.spec.ts`; `src/operator-ui/styles/overview.css` holds
 the page's styles.
 
 `src/operator-ui/config-summary.ts` maps the snapshot and its provenance to

package/documentation/providers.md

@@ -7,6 +7,95 @@ roster](./integrating.md#add-or-remove-a-connector) covers the general
 procedure and the providers not listed here. Agent guidance for each
 provider ships with its connection's usage guide, not here.
 
+## Granola
+
+```ts
+import { granola } from "@zackbart/connecta/providers/granola";
+
+const notes = granola("granola", { purpose: "Shared workspace meeting notes" });
+```
+
+Use a **workspace API key**, created by a Business or Enterprise workspace
+admin in Granola desktop Settings → Connectors → Workspace API keys → Create
+new key. Save it in this connection's credential slot through the operator UI;
+configure an encrypted vault as described in [shared credentials](./auth.md#connect-a-shared-credential).
+The shared, single-secret field is `value`. The provider fixes the origin to
+`https://public-api.granola.ai`, uses bearer authentication, and exposes reads
+only. It accepts `purpose`, optional `title`, `instructions`, and
+`maxResultBytes` and the common `readOnly` restriction. Even `readOnly: false`
+exposes only the five reviewed reads; it accepts no inline secret, origin override, personal auth
+scope, or option enabling writes.
+
+Workspace keys belong to the workspace, survive their creator leaving and do
+not expire; an admin can revoke them. They reach public notes and spaces with
+Granola API access enabled. For an existing space an admin uses Integrations →
+Granola API → Allow access with a workspace API key. Folders inherit the space
+setting. Workspace ownership does not grant unrelated private notes or the
+owner's private handwritten notes. Discover accessible IDs before filtering.
+Only notes with a generated summary and transcript are returned; a 404 does
+not prove absence. A successful credential test confirms accessible spaces,
+not the key's ownership type or access to every meeting. Granola enforces
+these permissions; Connecta cannot infer workspace versus personal key type
+from the secret. Do not substitute a personal API key or MCP OAuth token.
+
+The REST surface is `granola_api_search`, `granola_api_details`, and
+`granola_api_read`. Search discovers API operations, not meeting content.
+Reads cover `/v1/notes`, `/v1/notes/{note_id}`,
+`/v1/notes/{note_id}/transcript`, `/v1/folders`, and `/v1/spaces`. Use API IDs
+(`not_`, `fol_`, `spa_`), not UUIDs copied from web links. Date/folder/space
+filters and response `fields` narrowing follow the reviewed operation details.
+Audit, legal holds, webhook management and writes are refused, even if their
+contracts appear in operation discovery.
+
+Omit `query.cursor` on the first read. Continue with `page.nextCursor` as the
+top-level `cursor`, retaining the path and query filters. Continuations are
+bound to that request and are not raw Granola tokens. The vendor uses
+`query.page_size`: notes/folders/spaces default to 10 with maximum 30;
+transcripts default to 50 with maximum 100. Empty pages can have more data.
+No total count is inferred. HTTP 413 when using `include: "transcript"`
+requires a new note-detail read without include and paged transcript reads;
+the provider sends no hidden fallback requests. Photo download URLs grant
+unauthenticated access and are always withheld. Meeting text and sent
+credentials cross the same value-safety boundary before selection or paging.
+
+Granola documents 25 requests per 5-second burst and 5 requests/second
+sustained, shared across the workspace key's scope. The default per-runtime
+admission is 25 calls in a rolling 5-second window with concurrency 2. Other
+processes and integrations share the vendor allowance; the local counter
+cannot enforce a workspace-wide limit. A 429 returns `rate_limited` and
+Retry-After when supplied (otherwise a 5-second hint); calls are not retried
+automatically. Requests have a 30-second deadline and 4 MiB response ceiling.
+Oversized responses fail without presenting a partial success; inline result
+cuts retain the standard `truncated` paths.
+
+For hosted Granola MCP, use a distinct generic `remoteMcp()` connection to
+`https://mcp.granola.ai/mcp` with its user OAuth or enterprise-managed
+authorization. Granola MCP does not accept workspace API keys or service
+accounts. Its natural-language search is not a REST-provider capability.
+See [Granola's workspace-key guide](https://docs.granola.ai/help-center/sharing/integrations/granola-api#workspace-api-keys)
+and [API overview](https://docs.granola.ai/introduction).
+
+### Migrate a deployment-local Granola API adapter
+
+Replace the local `api("granola", …)` construction with
+`granola("granola", { purpose: "Shared workspace meeting notes" })`, retaining
+the same encrypted vault, encryption key, connector ID, shared owner and
+single-secret `value` field. The provider reuses that credential without
+copying it. Existing addresses `granola.granola_api_search`,
+`granola.granola_api_details`, and `granola.granola_api_read` remain stable.
+Keep existing pool references to `granola`. A differently named or personal
+credential field requires the operator to save a workspace key in the shared
+slot; do not read out or copy stored secrets through an agent.
+
+Compare local argument contracts before replacing the factory: the maintained
+search is operation discovery, details uses an indexed operation, and read
+uses a relative path and query. Replace raw `query.cursor` continuations with
+the bound top-level `cursor`, and start new pagination sequences after the
+upgrade. Responses use `{ status, data, page? }`. Remove local write tools or
+natural-language-search assumptions; do not keep duplicate factories with the
+same connector ID. If a local adapter used other tool names, update its
+callers explicitly. No data migration or downstream write is required.
+
 ## API sources and tool inventory
 
 Maintained providers pair reviewed API contracts and indexes with Connecta's
@@ -143,6 +232,20 @@ discovery for your deployment's catalog.
 
 </details>
 
+<details>
+<summary>Granola (3 tools)</summary>
+
+[Setup](#granola). **API source:** [Upstream OpenAPI](https://docs.granola.ai/api-reference/openapi.json).
+
+- **Named reads:** None.
+- **Named writes:** None.
+- **API reads:** `granola_api_details`, `granola_api_read`, `granola_api_search`.
+- **API writes:** None.
+
+**Contributor evidence (optional):** [contracts, adapters and review](https://github.com/zackbart/connecta/tree/main/src/providers/granola).
+
+</details>
+
 <details>
 <summary>Overflow (17 tools)</summary>
 
@@ -1318,6 +1421,13 @@ would change existing payment settings. Deletes, voids, delivery, payment
 execution, batch and other accounting writes remain unavailable. The API hatch
 refuses POSTs even when named writes are enabled.
 
+Sparse field preservation, a current SyncToken and requestid do not establish
+that an invoice update cannot send email. For example, changing only DueDate
+on an invoice with NeedToSend and enabled card/ACH payments retains those
+settings; omitting email fields does not disable them. Do not reset delivery or
+payment settings to work around the unavailable update, or replace the invoice
+with a new one. No unsent-only update tool is currently exposed either.
+
 Each write requires `requestId`, a stable identifier for the exact intent,
 unique across all requests/tools for this company: 1–50 ASCII letters, digits,
 underscores or hyphens, beginning with a letter or digit. It is sent as Intuit's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.36.0",
+  "version": "0.36.2",
   "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.",
@@ -107,6 +107,10 @@
       "types": "./dist/providers/gmail/index.d.ts",
       "import": "./dist/providers/gmail/index.js"
     },
+    "./providers/granola": {
+      "types": "./dist/providers/granola/index.d.ts",
+      "import": "./dist/providers/granola/index.js"
+    },
     "./providers/overflow": {
       "types": "./dist/providers/overflow/index.d.ts",
       "import": "./dist/providers/overflow/index.js"
@@ -158,6 +162,10 @@
     "./worker": {
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
+    },
+    "./google": {
+      "types": "./dist/google.d.ts",
+      "import": "./dist/google.js"
     }
   },
   "scripts": {
@@ -191,7 +199,7 @@
     "preeval:outcomes": "node scripts/generate-version.mjs && pnpm run build:operator-ui",
     "eval:perf": "tsx eval/run-perf.ts",
     "eval:report": "tsx eval/report.ts",
-    "check:static": "node --test scripts/check-provider-exemptions.test.mjs && pnpm run format:check && pnpm run check:providers-generated && pnpm run check:docs && pnpm run check:changes && pnpm run check:operator-ui && pnpm run check:clerk-sdk && pnpm run check:lint && pnpm run check:unused && pnpm run typecheck",
+    "check:static": "pnpm run format:check && pnpm run check:providers-generated && pnpm run check:docs && pnpm run check:changes && pnpm run check:operator-ui && pnpm run check:clerk-sdk && pnpm run check:lint && pnpm run check:unused && pnpm run typecheck",
     "check:build": "pnpm run build && pnpm run check:declarations && pnpm run check:bundle",
     "check:fast": "pnpm run check:static && vitest run --config vitest.config.node.ts --changed origin/main --passWithNoTests",
     "check": "pnpm run check:static && pnpm run test && pnpm run check:build",

package/templates/node/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.36.0",
+    "@zackbart/connecta": "0.36.2",
     "quickjs-emscripten": "0.32.0",
     "undici": "6.29.1"
   },