@zackbart/connecta 0.40.0 → 0.42.0

package/documentation/auth.md

@@ -295,7 +295,7 @@ It has no queue and no configuration option. When full, a request receives HTTP
 `error: { code: "authentication_busy", message: "Authentication capacity reached.", retryable: true }`.
 The operator log records only the checked `authentication_busy` reason, never
 credentials or identity-provider diagnostics. Retry after the indicated delay;
-Connecta does not automatically retry the authentication.
+Connecta does not automatically retry authentication, except for one rejected Cloudflare Access identity lookup inside its existing deadline (see [Access on Workers](#cloudflare-access-on-workers)).
 
 Underlying work stays charged until it settles, including cancellation cleanup.
 A caller leaving alone never releases capacity. After an authorization's hard
@@ -399,7 +399,9 @@ This bound is independent of MCP request/program admission and downstream call
 limits. `Mcp-Method: subscriptions/listen` still defers its MCP request permit:
 after authentication and endpoint admission, a body-confirmed modern listen is
 refused promptly even when execution capacity is full. It always passes the
-authentication bound, and no request body is read before authentication.
+authentication bound, and the MCP route reads no request body before
+authentication. On Node, `listen()` has already buffered the body up to its own
+[pre-auth cap](./deploying.md#start-on-node) before core sees the request.
 
 Routes that do not invoke an inbound verifier consume no authentication slot:
 health, public OAuth discovery and client metadata, UI shells and static assets,
@@ -558,6 +560,7 @@ createConnecta({
   storage,
   agents: ["assistant", "ci"],
   accessTokens: accessTokens(storage),
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   ui: operatorUi(),
   maintainers: ["your-operator-id"],
@@ -948,6 +951,7 @@ cache entries remain partitioned by the admitted pool.
 createConnecta({
   storage,
   accessTokens: accessTokens(storage),
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   readOnly: false, // required; pools without their own readOnly inherit it
   maintainers: ["user_owner"],
@@ -971,19 +975,19 @@ warning says, every pool path answers the 404 because nobody can be a member,
 and every agent endpoint answers the machine-only 401 because no agent can be
 admitted.
 
-| Rule         | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers and the unique member pool to other people. Neither intersects with or widens anything.                                                                                                                                         |
-| Refusal      | A person with zero or several memberships at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer` (zero memberships), `ambiguous_pool` (several memberships), `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                     |
-| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                                                                                     |
-| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the six meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                      |
-| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` append it to the MCP `initialize` instructions after `This endpoint: `; a maintainer at plain `/mcp` and a pool without one serve the shared instructions unchanged. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                       |
-| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, mixed people and agent membership (a `ConfigError` naming the pool), unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 characters of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
-| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                                                                                          |
-| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                                                                                             |
+| Rule         | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers and the unique member pool to other people. Neither intersects with or widens anything.                                                                                                                                                |
+| Refusal      | A person with zero or several memberships at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer` (zero memberships), `ambiguous_pool` (several memberships), `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                            |
+| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                                                                                            |
+| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                                 |
+| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` place the description before the rest of the MCP instructions; a maintainer at plain `/mcp` and a pool without one serve none. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                                                                    |
+| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, mixed people and agent membership (a `ConfigError` naming the pool), unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 UTF-16 code units of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
+| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                                                                                                 |
+| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                                                                                                    |
 
 Pool descriptions are trimmed before validation. The remaining text must be
-1 to 500 characters and contain no C0 or C1 control characters (including tabs,
+1 to 500 UTF-16 code units (non-BMP characters such as emoji count as two units) and contain no C0 or C1 control characters (including tabs,
 newlines, and NEL U+0085), LINE SEPARATOR (U+2028), or PARAGRAPH SEPARATOR
 (U+2029).
 
@@ -1102,6 +1106,7 @@ const team = [
   { handle: "bob", id: "user_bob", email: "bob@example.com" },
 ];
 createConnecta({
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   storage,
   accessTokens: accessTokens(storage),
@@ -1250,6 +1255,7 @@ const workspace: GoogleWorkspaceOptions = {
 };
 
 createConnecta({
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   storage,
   accessTokens: accessTokens(storage),
@@ -1364,21 +1370,34 @@ Each owner of an OAuth connector (the deployment when shared, each principal
 when personal) has one **grant record**, `oauth:grant` in the connector's
 namespace: the live **epoch**, the latest consent's state digest, and one
 authorization server's client registration, tokens, and discovery. Each
-consent has a **flow record**, `oauth:flow:<sha256(state)>`, holding its
-epoch, consent URL, and PKCE verifier for fifteen minutes; the state itself is
-stored nowhere.
+consent has a **flow record**, `oauth:flow:<sha256(state)>`, holding its epoch
+and timestamp, its binding to the selected server and client, its consent URL,
+and its PKCE verifier for fifteen minutes; the state itself is stored nowhere
+outside that URL.
 
-With a vault, the grant's body and each verifier are sealed with its AES-GCM
-key, the additional authenticated data naming the connector, owner partition,
+With a vault, the grant's body and each flow record's binding, consent URL and
+verifier are sealed with its AES-GCM key, the additional authenticated data naming the connector, owner partition,
 record, and epoch, so ciphertext moved to another connector, principal,
 record, or epoch does not open. Anything that fails to open (tampered, or
 under a rotated key) reads as absent: `auth_required` and a logged warning.
-The epoch, consent URL, and state digest stay plaintext and authenticate
-nothing. A plaintext body written before the vault could seal is sealed where
+The epoch, timestamp, and state digest stay plaintext and authenticate nothing. A plaintext body written before the vault could seal is sealed where
 it lies on first read, by compare-and-set. An [`api()` OAuth
-connector](#downstream-oauth-on-api) stores no client. A vault without the
-optional `seal`/`open` members keeps the body plaintext with a startup
-warning; no vault, plaintext as always.
+connector](#downstream-oauth-on-api) stores no client.
+
+`createConnecta` throws when a configured vault lacks `seal` or `open` and any
+connector has `startAuth`. A vault without them still works for deployments with
+no OAuth connector. To migrate, use `encryptedCredentialVault(storage, key)` or
+add both methods; grants stored plaintext are then sealed on first read as above.
+
+**With no vault, the guarantee is narrower.** Nothing is encrypted at rest: the
+grant's body and the PKCE verifier are plaintext, and a configured URL's path can
+appear in them. The flow record is minimized instead. It stores no consent URL,
+and its binding keeps no URL userinfo, query or fragment, in plaintext or in its
+unkeyed discovery digest. Connect, callback and restart still work, and two things
+differ. A repeated non-forced start mints a fresh consent rather than handing the
+pending URL back; earlier links stay valid until their epoch ends. A change confined
+to a URL's query or fragment does not fence a pending consent.
+Use a vault wherever stored OAuth state must be protected.
 
 The body also holds `expiresAt`, the epoch milliseconds the stored access token
 expires: its `expires_in`, counted from just before the request that issued it
@@ -1423,7 +1442,7 @@ longer live; one left behind cannot complete and expires with its link.
 `authorize_connector` issues the same browser link, with `force` carried in the
 signed handoff. On hosts without URL elicitation, direct and program auth
 failures and search/describe catalog failures include the same authorization
-handoff. The admitted registry and management permission govern issuance.
+handoff. A declined or cancelled URL elicitation returns it too. The admitted registry and management permission govern issuance.
 Each call or program run shares at most one handoff per connector; errors never
 request a forced restart. Signed links retain their fifteen-minute expiry,
 initiating-user and owner binding, origin check, and single-use browser nonce.
@@ -1662,7 +1681,7 @@ If the refresh fails instead, whatever it met (a dead grant, a waiter
 deadline, the caller leaving), or hands back the token the API just
 rejected, the 401's verdict stays:
 `downstream_oauth_required`, never retryable, with `reconciliationRequired`
-and `writeOutcome: "unknown"`, and an `authorize_connector` handoff that says
+and `writeOutcome: "unknown"`, and a handoff that says
 to re-read the target before any fresh call. A read is refreshed and sent
 once more. MCP sends a tool only once when either its effective classification
 or its original server hints say write. A deployment write-to-read override
@@ -1993,9 +2012,14 @@ any registered form is still withheld, however short.
 Identifiers sent beside a credential are matched whole only, because consent
 URLs and vendor metadata carry their parts by design: a confidential OAuth
 client's ID, a Basic username beside a password of at least eight characters,
-and credential-slot fields named as identifiers (ending in `id`, `user`,
-`username`, `login`, or `email`, or starting with `public`). A Basic username
-beside a shorter or empty password is the credential itself and is fully
+credential-slot fields named as identifiers (ending in `id`, `user`,
+`username`, `login`, or `email`, or starting with `public`), and the two headers
+maintained providers declare public from their vendors' contracts: Cloudflare's
+Global API Key `X-Auth-Email` and Overflow's `x-client-id`. A value in either
+that holds whitespace, as an auth scheme's framing does, is a credential. Any
+other header or query parameter is never public by name: `remoteMcp()` and
+`api()` auth headers under any name are credentials, fully matched. A Basic
+username beside a shorter or empty password is the credential itself and is fully
 matched. Query parameters named as continuation cursors (`pageToken`,
 `nextPageToken`, `next_token`, `continuationToken`, `syncToken`) are public
 result state and are not registered. Header values a connector adds to token
@@ -2083,11 +2107,17 @@ targeting the host's private network:
 - A URL on the connector's configured origin is trusted; the operator wrote it.
 - 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.
+  `100.64/10`, `0/8`, `192.0.0/24`, `192.0.2/24`, `192.88.99/24`, `198.18/15`,
+  `198.51.100/24`, `203.0.113/24`, `224/4`, `240/4`, `::`, `::1`, any IPv6
+  address outside global unicast `2000::/3` (which covers `fc00::/7`,
+  `fe80::/10`, `fec0::/10`, `ff00::/8` and `64:ff9b:1::/48`), `2001::/23`,
+  `2001:db8::/32`, or `3fff::/20`. An IPv6 address carrying an IPv4 address in
+  mapped, compatible, translated, NAT64 (`64:ff9b::/96`) or 6to4 (`2002::/16`)
+  form is judged by the address it carries.
 - 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.
+  working. Of the IPv4-carrying forms, only IPv4-mapped loopback counts as
+  loopback. 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`. Resource-metadata origin
@@ -2098,10 +2128,22 @@ and the grant requires re-consent. Redirects cannot route around the
 rule; token requests never follow them, and resource redirects follow only
 same-origin hops.
 
-The check is syntactic: it reads the host after the WHATWG URL parser folds
-`2130706433` and `0x7f.1` into `127.0.0.1`, and never resolves a name — the
-Workers-safe core has no DNS. A public name resolving or rebinding to a private
-address is out of scope; a host that must stop that needs an egress policy.
+The shared check reads canonical URL syntax (including legacy IPv4 spellings).
+On Node, the owned transport also resolves learned hosts immediately before
+connecting, refuses the whole answer set if any IPv4 or IPv6 address violates
+the same rules, and pins the connection to a checked address. TLS SNI and
+certificate validation retain the original hostname, including through a proxy.
+Proxy TLS authenticates the proxy hostname separately from destination TLS.
+Resolution uses request-owned A/AAAA queries, cancelled when the request ends
+and bounded to ten seconds even without a caller deadline. Only absent address
+families may be omitted; resolver failures refuse the request. These DNS queries
+do not consult OS hosts-file aliases.
+Each redirect hop is checked. Configured origins remain exempt. Resolution
+refusals are typed, non-retryable, and send no destination request.
+
+Workers exposes no connection-time DNS hook and has no route to private networks;
+its behavior remains the shared syntactic check. The shared core never imports
+Node networking or the optional undici peer.
 
 Downstream advertisements choose consent destinations, never destinations for
 existing grants. Tokens and registered clients bind to their issuing server;
@@ -2228,7 +2270,9 @@ the first request on a fresh instance. It grants no identity and never falls
 back to another provider. Missing context without an assertion still returns 401. An unusable trusted AUD returns retryable 503 with
 `problem: "access_audience_invalid"`; it never proceeds to identity lookup.
 A rejected human identity, including a service identity or an unusable user
-id, returns 403. A thrown identity lookup or its five-second deadline returns retryable
+id, returns 403. A thrown identity lookup gets one retry after 100–250 ms of
+jitter, within the original five-second deadline. A hanging lookup is never
+retried concurrently. The second rejection or the deadline returns retryable
 503 with `problem: "identity_unavailable"` and `Retry-After: 1`. Every refusal
 carries `Cache-Control: no-store`; every unavailable-verification 503 carries
 `Retry-After: 1` and no `WWW-Authenticate` challenge. None of these failures admits an identity,
@@ -2246,9 +2290,24 @@ identifies the generic route fallthrough, `authorization_header_invalid` a
 malformed header, and `authentication_failed` an unclassified provider refusal.
 Access verification 503s emit `[connecta] Cloudflare Access verification unavailable`
 with the same facts and `access_context_unavailable`, `access_audience_invalid`,
-or `access_identity_unavailable`. These records contain no header values,
+or `access_identity_unavailable`. Identity lookup failures additionally carry
+checked `identityLookup` facts: `outcome` (`timeout` or `rejected`), `durationMs`,
+`cold` (whether this was the isolate's first identity lookup), and `inFlight`
+(the isolate's lookup attempts still pending when the failure was recorded; this
+request's own attempt counts only while it is pending, so a hung lookup counts
+itself, and a rejected lookup or a deadline during retry backoff does not).
+These records contain no header values,
 assertions, cookies, identities, URLs, response bodies, or exception text.
 
+Identity lookups stay request-owned: Connecta neither coalesces them across
+requests nor caches identity results. A caller-supplied assertion header is
+not an identity cache key. Failed identity lookups always refuse admission.
+
+After an authorized release, validate this mitigation with about 20 concurrent
+sessions. Count runs containing `identity_unavailable`, targeting fewer than
+1% of runs; distinguish `timeout` from `rejected` in the checked lookup facts.
+A passing local concurrency fixture does not establish production acceptance.
+
 Protect the Worker with a Worker-level Access application whose destination is
 `{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
 hostname-level application blocks the URL but does not attach `ctx.access` to
@@ -2293,7 +2352,15 @@ tokens by default, both JWT and opaque. Verified `aud` or `resource` must
 contain the endpoint's exact canonical URL from protected-resource metadata.
 If both claims are present, both must match. Trailing slashes, case, queries,
 and fragments are not normalized. `/mcp` and `/mcp/support` are distinct
-resources. Set `publicUrl` behind an internal origin.
+resources.
+
+Clerk needs a fixed deployment URL. Set `ConnectaConfig.publicUrl`, or
+`clerkAuth({ publicUrl })` when only Clerk should use it; `createConnecta` throws
+when neither is set, on Node and on Workers. Both token `resource` checks and the
+session `azp` pin read this value, so a request's `Host` and `X-Forwarded-Proto`
+never decide them. There is no implicit loopback default: a local deployment names
+its origin, such as `http://localhost:8787`. The Node template does this when
+`PUBLIC_URL` is unset.
 
 ```ts
 clerkAuth({ publishableKey, secretKey,
@@ -2548,6 +2615,30 @@ survives every round. Rotation invalidates outstanding states.
 Each state admits one retry through a connector-scoped storage CAS, including
 decline and cancel. Concurrent or repeated consumption is refused before
 dispatch, so retries cannot fork into sibling forced connection links.
+A decline or cancel returns one fresh link, issued only after that state verifies
+and the same management check as the prompt passes, so a refusal offers nothing
+this caller could not already request. The link is sealed like the prompt's and
+keeps the prompt's force.
+
+URL `accept` is consent to the interaction, not evidence that a browser navigated:
+the retry normally reaches Connecta before any visit does. So every link a flow
+issues stays live until it is visited or expires, whichever round or refusal
+issued it. A `force: true` flow resets once, through one atomic claim on an identity
+its links share:
+
+| A verified visit finds the reset | The visit                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| Unclaimed                        | Claims it and runs `startAuth({ force: true })`                                 |
+| Still running in another visit   | Returns 409 and spends nothing, so reloading the same link retries              |
+| Started                          | Spends its link and runs `startAuth({ force: false })`, continuing that consent |
+| Failed                           | Claims it again and starts afresh, so a failure never reuses the old grant      |
+
+A failed link is spent, but the flow is not: its other links, or the next prompt's,
+take over. The record outlives every link the flow can issue. If the process holding
+the claim dies, nothing settles it, so the flow's links keep returning 409 for up to
+thirty minutes, and that response says to start a new connection request. A new
+`force: true` call is a new flow with its own reset, so it recovers at once. Each link still works
+once. An unforced flow's links stay independent and never reset.
 The host records each entered call's classification, catalog freshness and
 classification digest in private invocation state, along with auth failure origins. Writes may elicit only
 when Connecta's own credential resolution fails before invoking the connector:
@@ -2582,14 +2673,11 @@ reads this key; connector contexts and guest APIs cannot reach the vault.
 Explicit authorization retries require a completed browser start (including
 its reset and consent binding), valid stored credential fields where declared,
 and a healthy passive connector status where available before completing.
-An in-progress start cannot complete against an old grant. A forced flow switches to
-Continue after that visit, so another prompt cannot restart pending consent.
-Failed starts remain single-use but do not block a later successful attempt.
-Before checking completion, unspent links in the retry flow are atomically
-retired so an older forced link cannot begin a reset during the status check.
-A Continue link issued during a pending forced start is bound to that
-predecessor and cannot be consumed unless the predecessor starts successfully.
-If it fails, the next prompt requests a fresh restart instead of reusing the old grant.
+An in-progress start cannot complete against an old grant: only a link whose start
+finished counts toward completion, and the next prompt carries the same flow, so it
+cannot restart pending consent. Failed starts remain single-use but do not block a later
+successful attempt. A link visited during the completion check continues the
+attempt that check is judging, and cannot reset it.
 
 The `/connect` link issued by the elicitation boundary encrypts its browser
 handoff with the vault's `seal`/`open` methods before signing it. The URL carries
@@ -2658,12 +2746,13 @@ still serve configured credentials. Both routes accept only GET, otherwise retur
 `form_post` is unsupported. Clerk's session-only policy applies regardless of method.
 
 The fifteen-minute signed handoff carries connector ownership, initiating principal, deployment origin, nonce,
-restart mode, and any predecessor link binding. New links use versioned, length-prefixed fields instead of
+restart mode, and, for a forced flow's later links, the flow they share a reset with. New links use versioned, length-prefixed fields instead of
 JSON, with unpadded base64url payload and signature segments. Ordinary handoffs use an opaque wire encoding,
 not encryption; URL elicitation also seals those fields as described above. Copy the complete URL unchanged.
 The signature authenticates the exact version and payload text. Tampered or re-encoded links return
 `Invalid or expired connection link. Request a new link from connecta.` Pre-upgrade signed JSON and sealed
-v2 links still verify against their original text and expire after their original fifteen minutes.
+v2 links still verify against their original text and expire after their original fifteen minutes. A link from
+an earlier version that names a predecessor link, in any format, returns the same refusal, and a new link replaces it.
 
 Configure `vault: encryptedCredentialVault(storage, key)`, which derives its HMAC key with HKDF. Custom vaults need `signOAuthHandoff` and `verifyOAuthHandoff`; without a signing vault, links cannot be
 issued or accepted. A link grants no identity. After identity and permissions pass, its nonce is consumed
@@ -2900,12 +2989,12 @@ owner's access token as `Authorization: Bearer` with these rules:
 - Whatever that recovery meets, a write's failure is never retryable and its
   outcome is unknown. Until a refresh succeeds the 401's verdict stands:
   `downstream_oauth_required`, which the invocation marks
-  `reconciliationRequired`, with the `authorize_connector` handoff, whether
+  `reconciliationRequired`, with the authorization handoff, whether
   the refresh was [dead](#refresh-failures), lost after it was sent, raced
   by a disconnect or reset, failed in storage or contention, or handed back
   the token the API just rejected, which renews nothing.
 - No grant, a second 401, or a [dead refresh](#refresh-failures) means
-  `downstream_oauth_required`, directing `authorize_connector`. Refresh waiter deadlines
+  `downstream_oauth_required`, carrying the authorization handoff. Refresh waiter deadlines
   return retryable `unavailable` for a read. Latch second 401s for the request scope,
   preventing repeated refreshes by later program calls.
 - Handlers can name no storage, sealing, or owner partition; the registry owns them.
@@ -2923,9 +3012,27 @@ 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
-configured token endpoint healthy without downstream probes and never start
-authorization. `oauth` and
+Disconnect match `remoteMcp()`. Status reads do not probe tokens, start OAuth,
+or write grant state. A grant for the configured token endpoint starts as `ok`;
+a real API 401 records `refused` and status becomes `auth_required`. A real API
+2xx records `accepted`. Other HTTP statuses do not establish an auth outcome.
+A persisted refusal does not block a later invocation: the API may have recovered,
+and an accepted response restores `ok`. Within the failing request, a second 401
+still latches authorization failure. Connect on a refused grant begins fresh consent
+rather than reporting existing tokens as healthy. Maintained OAuth providers record
+these same outcomes for initial and replayed requests. Repeated identical outcomes
+for the current revision do not rewrite the grant.
+Each consent and refresh advances a monotonic token revision within its grant
+epoch and clears the prior observation in the same compare-and-set write.
+Call observations carry the epoch and revision read with their token and are
+accepted only while both still match the live grant. No wall clock orders
+observations. Reconsent with an identical token still advances the revision.
+The observation stores only its revision and the `accepted`/`refused` enum;
+arguments, response bodies, code and error text are excluded. A declared oversized
+401 records refusal without reading its body, including on a replay. Normal Connect
+resets only while the refused epoch, revision and outcome it read still match;
+a concurrently recovered grant is preserved. An observation
+storage failure does not replace the already received API response. `oauth` and
 `credential` are exclusive per connector, giving `auth_required` one recovery.
 For providers offering both, deployment config chooses; handlers check `ctx.oauth`.