@zackbart/connecta 0.24.4 → 0.26.0

package/documentation/auth.md

@@ -51,8 +51,11 @@ deployments and providers that return no identity share one result partition.
 
 `identity.connectorAccess` returns `"all"` — the default — or a list of grants:
 a declared connector id opens every tool on it, a `connector.tool` address opens
-that tool alone, and grants are additive, so a bare id beside addresses for the
-same connector means the whole connector. It governs discovery and use alike.
+that tool alone, and `{ tool: "connector.tool", requireReadOnly: true }` opens
+that exact tool only while the loaded catalog says it is explicitly read-only.
+The guarded form accepts no connector-wide grant. Grants are additive, so a
+bare id or an unrestricted address beside a guarded address wins for that
+tool. It governs discovery and use alike.
 
 Tool grants are enforced in the scoped registry view, below the catalog service,
 so `search_tools`, both call tools, a program's `connecta.search`,
@@ -69,6 +72,84 @@ There is no *caller-selected* tool set. A narrower slice is a branch in this
 resolver or a config-declared pool; a bot that needs its own slice is its own
 bearer subject. What a request may never do is name its own scope.
 
+### Team read sets
+
+`connectorAccess` is the supported way to give Engineering and Marketing
+different views of one deployment. Keep membership in deployment code and
+review the exact tool addresses you intend to grant:
+
+```ts
+const engineering = new Set(["engineer-id"]);
+const marketing = new Set(["marketer-id"]);
+const engineeringGrants = ["issues", { tool: "campaigns.list", requireReadOnly: true }] as const;
+const marketingGrants = ["campaigns", { tool: "issues.search", requireReadOnly: true }] as const;
+
+createConnecta({
+  auth: cloudflareAccessAuth(),
+  identity: {
+    connectorAccess: ({ principal }) => {
+      const id = principal?.id;
+      if (!id) return [];
+      return [...new Set([
+        ...(engineering.has(id) ? engineeringGrants : []),
+        ...(marketing.has(id) ? marketingGrants : []),
+      ])];
+    },
+  },
+  connectors: [issues, campaigns, billing],
+  executor,
+});
+```
+
+Here Engineering sees every `issues` tool and only `campaigns.list`;
+Marketing sees every `campaigns` tool and only `issues.search`. Neither sees
+`billing`. Someone in both groups gets both connectors in full because grants
+are additive. An unknown or unprincipalled identity gets an empty view. The
+example assumes the two exact tools have been reviewed as read-only; the names
+themselves carry no safety meaning. The guarded grants also check the current
+loaded annotations before discovery or use. Use a stable authenticated
+principal or subject for membership, never a request header or tool argument. A pool can
+narrow any of these views on its endpoint, but cannot make plain `/mcp` narrower.
+
+New tool names are excluded until added to a reviewed list. A removed or
+renamed name is unreachable and warned when the scoped view reads its catalog.
+For a guarded grant, missing, false, or contradictory read-only annotations
+also remove that tool from discovery and every invocation path, including
+`call_destructive_tool` and approval-exempt programs. An unrestricted exact
+string grant has the earlier behavior: a tool that changes from read to write
+stays granted, though `call_tool` refuses it and the write paths take over.
+Changing schema alone does not revoke either kind of grant. Review schemas,
+annotations, and downstream behavior before changing lists or upgrading a
+maintained provider. An arbitrary remote MCP catalog can drift without a
+package upgrade; a valid stale cached catalog may keep its earlier
+classification until refresh. A downstream can also keep a read-only
+annotation while changing the behavior behind it. For `api()` tools, the
+deployment author owns both declaration and handler. Connecta enforces the
+loaded declaration, not the downstream's promise of no side effects. A
+restricted downstream credential adds protection where the provider offers
+one, but does not replace the per-identity grant.
+
+When the resolver returns `[]`, connector-level discovery and the connection
+UI have no connectors to show. An address-only grant can leave a connector
+visible while its named tool is absent; the tool stays unreachable. A failed
+remote catalog load is an error, not an empty successful catalog; a valid stale
+catalog may be served within its configured stale window. A guarded grant
+whose tool loses qualification can leave its connector visible with no tools.
+Personal OAuth ownership and credential-administration permissions remain separate from
+visibility. These are the checks for a team read set:
+
+| Boundary | Expected result for a reviewed address and an excluded write |
+| --- | --- |
+| `search_tools`, `describe_tools`, connector guides | Show the granted address; omit the write. |
+| `call_tool` | Invoke an explicitly read-only granted address; return `unknown_tool` for the write. |
+| `call_destructive_tool` | Return `unknown_tool` for the excluded write, without dispatch. |
+| `execute_code` search, describe, call | See granted tools only; refuse the excluded write. A granted write still follows the separate approval rules. |
+| Connection UI | List granted tools only; never turn visibility into credential administration. |
+| `/mcp/<pool>` | Intersect its grants with the identity view; plain `/mcp` keeps the identity view. |
+
+Integration tests in `test/identity-scope.test.ts` exercise these paths and
+the older unrestricted exact-grant behavior.
+
 ## Pools
 
 A pool is a named slice of the deployment served at its own endpoint,
@@ -149,6 +230,86 @@ partitions. Literal `auth: { type: "headers" }` cannot be personal, because its
 secret lives in deployment code; `remoteMcp()` refuses that combination at
 construction.
 
+## Downstream OAuth state at rest
+
+With a vault configured, a `remoteMcp()` OAuth connector's tokens, dynamically
+registered client (secret included), and PKCE verifier are sealed with the
+vault's AES-GCM key before they reach storage. The additional authenticated data
+names the connector, the owner partition, and the physical key, which carries
+the authorization epoch, so ciphertext copied to another connector, principal,
+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.
+
+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
+is one-way. An older release reads sealed state as unusable, so rolling back
+means authorizing again. A vault without the optional `seal`/`open` members
+keeps these values plaintext and draws a startup warning. Without any vault,
+nothing changes: the state is plaintext, as it always was.
+
+## Refresh failures
+
+A failed token refresh means one of two things, and connecta decides which
+from the token endpoint's answer, not the SDK's reading of it. A **dead grant**
+is any 4xx except 408, 425, and 429, or a 2xx carrying an OAuth `error` (GitHub
+answers `200 {"error":"bad_refresh_token"}`). It ends as `auth_required`, and
+the refused tokens are deleted on the spot, so no later request or isolate
+sends them again and the next `authorize_connector` goes straight to consent.
+An **outage** is a 5xx, 408, 425, 429, a network failure, or a 2xx that is not
+a token response. It ends as retryable `unavailable`, or `rate_limited` for a
+429, with `retryAfterMs` when the server sent `Retry-After`. The grant is kept,
+and a passive call writes no consent URL. Every request joined on the same
+in-flight refresh gets the same verdict, even when the request that sent the
+refresh is cancelled after the answer arrives: the refused tokens are deleted
+before anyone waiting is released, so a request arriving meanwhile joins the
+refusal instead of sending the dead token again.
+
+The SDK needs this help. On a refresh failure it cannot parse, or one marked
+`server_error`, it falls through to starting authorization, which reports a
+healthy grant as needing consent. It rethrows every other OAuth error
+untouched, which reports a dead grant as a generic outage and keeps re-sending
+it. So the refresh coordinator hands the SDK an answer it classifies correctly,
+and the provider hooks it calls next finish the job. The pinned SDK behavior is
+spelled out beside `refreshResponseOutcome`. An explicit authorization during
+an outage still falls through to consent, since that is what it asked for.
+
+## URLs a downstream advertises
+
+A `remoteMcp()` OAuth connector learns most of the URLs it fetches from the
+downstream itself: the `resource_metadata` in its 401 challenge, the
+`authorization_servers` in that metadata, and the token and registration
+endpoints the authorization server publishes. Connecta fetches every one of
+them server-side, so a compromised downstream could otherwise aim a Node or
+Docker host at its own network — cloud metadata at `169.254.169.254`, an admin
+panel on the LAN. Config is the security model, so the rule splits on it:
+
+- A URL on the connector's configured origin is trusted. The operator wrote it
+  down.
+- Any other URL must be `https` and must not name a private host: `localhost`
+  and `*.localhost`, `127/8`, `10/8`, `172.16/12`, `192.168/16`, `169.254/16`,
+  `100.64/10`, `0/8`, `::`, `::1`, `fc00::/7`, `fe80::/10`, or an IPv4-mapped
+  IPv6 form of any of those.
+- A connector configured on a loopback host may also learn loopback URLs, over
+  `http` too, so a local MCP server with a local authorization server keeps
+  working. LAN and link-local addresses stay refused.
+
+A refused URL is never requested. Discovery, registration, and code exchange
+fail with a non-retryable `connector_call_failed` that names the host and
+nothing else from the URL. A refused refresh never reaches the token endpoint,
+so there is no verdict to act on: the grant is kept, and the SDK falls through
+to consent as it does for any refresh it could not complete. Redirects cannot
+route around the rule, because the redirect policy only follows same-origin
+hops.
+
+The check is syntactic. It reads the host after the WHATWG URL parser has
+folded `2130706433` and `0x7f.1` into `127.0.0.1`, and it never resolves a
+name, because the Workers-safe core has no DNS. A public name that resolves to
+a private address, or rebinds to one after the check, is out of scope; a host
+that must stop that runs connecta behind an egress policy that does.
+
 ## Management permissions
 
 Visibility alone grants no authentication-management permission. Two independent