@zackbart/connecta 0.40.0 → 0.41.0

package/dist/url-safety.js

@@ -13,11 +13,11 @@
  * legacy IPv4 spelling (`2130706433`, `0x7f.1`, `0177.0.0.1`) into dotted
  * decimal and every IPv6 literal into compressed hex, so one canonical form is
  * all this module reads. It never resolves a name: that needs DNS, which the
- * Workers-safe core cannot do, and a name that resolves somewhere private — or
- * rebinds after the check — is out of scope. Pure Web API, no `node:` import.
+ * Workers-safe core cannot do. The owned Node transport additionally resolves
+ * and pins learned destinations at connect time. Pure Web API, no `node:` import.
  */
 function classifyIpv4(octets) {
-    const [a = 0, b = 0] = octets;
+    const [a = 0, b = 0, c = 0] = octets;
     if (a === 127)
         return "loopback";
     if (a === 0 ||
@@ -25,7 +25,14 @@ function classifyIpv4(octets) {
         (a === 172 && b >= 16 && b <= 31) ||
         (a === 192 && b === 168) ||
         (a === 169 && b === 254) ||
-        (a === 100 && b >= 64 && b <= 127)) {
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 192 && b === 0 && (c === 0 || c === 2)) || // IETF protocol, documentation
+        (a === 192 && b === 88 && c === 99) || // 6to4 relay anycast
+        (a === 198 && (b === 18 || b === 19)) || // benchmarking
+        (a === 198 && b === 51 && c === 100) || // documentation
+        (a === 203 && b === 0 && c === 113) || // documentation
+        a >= 224 // multicast, reserved, broadcast
+    ) {
         return "private";
     }
     return "public";
@@ -61,24 +68,35 @@ function ipv6Pieces(host) {
     return [...head, ...Array.from({ length: missing }, () => 0), ...tail];
 }
 function classifyIpv6(pieces) {
-    const [first = 0] = pieces;
-    const leadingZeros = pieces.slice(0, 5).every((piece) => piece === 0);
-    if (leadingZeros && pieces[5] === 0 && pieces[6] === 0) {
-        if (pieces[7] === 0)
-            return "private"; // ::
-        if (pieces[7] === 1)
-            return "loopback"; // ::1
+    const [p0 = 0, p1 = 0, p2 = 0, p3 = 0, p4 = 0, p5 = 0, p6 = 0, p7 = 0] = pieces;
+    const v4 = (high, low) => classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    // A transitional form reaches, at most, the IPv4 address it carries. Only a
+    // mapped address can reach this host, so only it stays `loopback`; every
+    // other non-public carrier is `private`, keeping it out of a loopback
+    // connector's learned URLs.
+    const carried = (high, low) => (v4(high, low) === "public" ? "public" : "private");
+    const zeros = p0 === 0 && p1 === 0 && p2 === 0 && p3 === 0;
+    if (zeros && p4 === 0) {
+        if (p5 === 0xffff)
+            return v4(p6, p7); // ::ffff:a.b.c.d mapped
+        if (p5 === 0) {
+            if (p6 === 0 && p7 === 1)
+                return "loopback"; // ::1
+            return carried(p6, p7); // :: and ::a.b.c.d compatible
+        }
     }
-    // ::ffff:a.b.c.d reaches the mapped IPv4 destination; classify that.
-    if (leadingZeros && pieces[5] === 0xffff) {
-        const high = pieces[6] ?? 0;
-        const low = pieces[7] ?? 0;
-        return classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    if (zeros && p4 === 0xffff && p5 === 0)
+        return carried(p6, p7); // ::ffff:0:a.b.c.d translated
+    if (p0 === 0x64 && p1 === 0xff9b && p2 === 0 && p3 === 0 && p4 === 0 && p5 === 0)
+        return carried(p6, p7); // NAT64
+    if (p0 === 0x2002)
+        return carried(p1, p2); // 6to4
+    // Global unicast is 2000::/3. Outside it: unique-local, link-local,
+    // site-local, multicast, local-use NAT64, reserved. Inside it, special-purpose
+    // 2001::/23 and documentation 2001:db8::/32 and 3fff::/20 are not destinations.
+    if ((p0 & 0xe000) !== 0x2000 || (p0 === 0x2001 && (p1 < 0x200 || p1 === 0xdb8)) || (p0 === 0x3fff && p1 < 0x1000)) {
+        return "private";
     }
-    if ((first & 0xfe00) === 0xfc00)
-        return "private"; // fc00::/7
-    if ((first & 0xffc0) === 0xfe80)
-        return "private"; // fe80::/10
     return "public";
 }
 /**

package/dist/utility-recovery.js

@@ -0,0 +1,33 @@
+/** Actions outside the tool namespace never invent a route on a serving surface. */
+export function utilityRecovery(code, message, retryable = false) {
+    return {
+        code,
+        message,
+        retryable,
+        nextAction: {
+            action: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "inspect_capabilities"
+                : code === "not_found"
+                    ? "recover_result"
+                    : "contact_operator",
+            purpose: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "Inspect the supported utility input and client capabilities before a fresh call. Never repeat a write whose outcome is unknown."
+                : code === "not_found"
+                    ? "Use a retained result handle if available. Otherwise report the missing output; never repeat a write to recover output."
+                    : "Ask the operator to restore availability. Retry reads only after recovery; reconcile any write whose outcome is unknown.",
+        },
+    };
+}
+/** Missing skill names need local discovery, never service restoration or result recovery. */
+export function skillLookupRecovery(message) {
+    return {
+        code: "not_found",
+        message,
+        retryable: false,
+        nextAction: {
+            tool: "skills",
+            arguments: {},
+            purpose: "List available skills, then fetch an exact name from that list.",
+        },
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.40.0";
+export declare const CONNECTA_VERSION = "0.41.0";

package/dist/version.js

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

package/dist/worker.js

@@ -99,6 +99,20 @@ export function workerExecutor(options) {
         // The SDK prepares its source/dispatchers against this inert loader.
         // Actual Loader and RPC acquisition belongs to the native program below.
         let prepared;
+        // Upstream 0.5.5+ answers every host call that settles after its
+        // evaluate() with a late-call error. Its inert evaluate stays pending
+        // until the native evaluation ends, so the SDK's gate stays open for the
+        // whole run and closes once the run is over or the lease is released.
+        let evaluating;
+        const evaluated = new Promise((resolve) => {
+            evaluating = resolve;
+        });
+        let settleUpstream;
+        const endUpstream = () => {
+            const settle = settleUpstream;
+            settleUpstream = undefined;
+            settle?.();
+        };
         const dispose = (resource) => Effect.sync(() => {
             try {
                 const method = Reflect.get(resource, Symbol.dispose);
@@ -309,7 +323,10 @@ const {
                             getEntrypoint: () => ({
                                 evaluate: (...evaluateArgs) => {
                                     acquisition.args = evaluateArgs;
-                                    return Promise.resolve({ result: undefined });
+                                    return new Promise((resolve) => {
+                                        settleUpstream = () => resolve({ result: undefined });
+                                        evaluating?.();
+                                    });
                                 },
                             }),
                         };
@@ -342,15 +359,21 @@ const {
                 const started = Date.now();
                 const operation = Effect.gen(function* () {
                     const setup = yield* Effect.tryPromise({
-                        try: () => new DynamicWorkerExecutor({
-                            loader,
-                            ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-                        }).execute(code, detached),
+                        try: () => {
+                            const upstream = new DynamicWorkerExecutor({
+                                loader,
+                                ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+                            }).execute(code, detached);
+                            // The SDK's own result, which settles only after endUpstream(),
+                            // carries nothing; the native evaluation below owns the outcome.
+                            upstream.catch(() => undefined);
+                            return Promise.race([upstream, evaluated.then(() => undefined)]);
+                        },
                         catch: (error) => error,
                     });
                     // Provider validation can return before the SDK reaches its loader.
-                    if (!prepared)
-                        return setup;
+                    if (setup !== undefined || !prepared)
+                        return setup ?? { result: undefined };
                     const load = prepared.load;
                     const args = prepared.args;
                     const open = () => Effect.suspend(() => released || resources.state._tag === "Closed"
@@ -369,7 +392,7 @@ const {
                             try: () => Reflect.apply(Reflect.get(entrypoint, "evaluate"), entrypoint, args ?? []),
                             catch: (error) => error,
                         });
-                    }).pipe(Scope.provide(resources));
+                    }).pipe(Scope.provide(resources), Effect.ensuring(Effect.sync(endUpstream)));
                     const result = yield* evaluation;
                     const outcome = result;
                     if (outcome.failure) {
@@ -407,6 +430,7 @@ const {
                 }));
             }).pipe(Effect.raceFirst(Deferred.await(stopped)), Effect.catchDefect((error) => Effect.fail(error)), Effect.ensuring(Effect.sync(() => {
                 runEnded = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();
@@ -420,6 +444,7 @@ const {
                 if (released)
                     return;
                 released = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();

package/documentation/architecture.md

@@ -1042,7 +1042,15 @@ run of K = 8 consecutive UTF-16 units of a registered form of a value at least K
 long, in the raw text or any JSON-decoded layer; text cut where the cut can end
 inside a form loses that unfinished tail, however short.** Runs formed from
 placeholder text and kept text or numbers are covered too; the placeholder
-itself is reserved replacement text. Registered forms are
+itself is reserved replacement text. The guarantee excludes an occurrence made
+entirely of reserved replacement text, including a run across the seam between
+adjacent markers, whether or not the registered form contains a complete
+`[redacted]`. For example, register `secretsecret` and `ted][red`, then redact
+`["secretsecret", "secretsecret"]`: the returned leaves may be
+`["[redacted]", "[redacted]"]`. Their joined projection spells the second
+registered value using only reserved replacement text; no original secret
+units survive. An occurrence that includes retained original text stays covered.
+Registered forms are
 the raw value, its URL/form encodings (either percent hex case), base64 and
 base64url, and the `Bearer `/`token ` framings. The framing words are public, so
 no indexed run starts inside them; a run reaching K units of the value is
@@ -3772,6 +3780,16 @@ change. All 88 declarations still exclude Effect and have complete references.
 
 ### Native remote MCP programs (contributor)
 
+Legacy session termination may read a token before rotation and send its DELETE
+on the wire after rotation. This is accepted only for bounded, headers-only
+termination of the old session, never for application traffic (`tools/call`,
+`tools/list`, or other RPCs). Connection scope close retains the same cleanup
+completion after revocation; later connector close joins it so the runtime's
+deferred hook (Workers `waitUntil`) owns the bounded tail. Abandoned leases from
+rotation and failed connects, and authorization exchange transports, retain their
+cleanup in that same request state. Termination and local close keep their
+existing one-second budgets; the caller-facing close window remains 100 ms.
+
 Remote MCP connection joins, credential and epoch checks, catalog intake,
 negotiation, calls, resources, Skills, auth and status compose native programs.
 `connectors/remote-mcp.ts` keeps the published options, the redirect guard and
@@ -3918,3 +3936,32 @@ cache. Exact authored names and complete authored matches precede API pointers;
 ordinary result limits, offsets, catalog failure disclosure and byte bounds apply.
 The published discovery contract states compilation, query and cache bounds.
 No request identity, signal, credential or promise enters a vocabulary cache.
+
+SQL catalog locating snapshots derive at most two manifest candidates from the
+stored generation alongside negotiation and generation rows. These candidates
+are request-local hints with exact config, owner and credential partitions.
+Complete chunk verification and a separate later primary generation and identity
+fence decide acceptance. OAuth invocation and dispatch reads stay separate.
+
+SQL result stashes write at most 64 trailing rows per awaited transaction, with one
+expiry sweep per batch. Header publication follows confirmed trailing writes in a
+separate transaction; uncertain writes retain their ledger charge until expiry.
+Custom storage keeps sequential writes.
+
+Admission observation sampling retains at most 256 scalar deadlines per live
+physical storage identity in an isolate. Only a recent valid stored timestamp
+or confirmed CAS populates it, for at most one minute. This telemetry cache
+never answers token admission; every request still checks current credentials.
+
+### Lexical token reuse (contributor)
+
+Search may retain four complete accepted catalog token indexes, bounded by an
+8 MiB estimate including key text, token strings, postings and structural slots.
+Identity includes complete served content (including schemas, classification and
+order), connector, physical store, owner partition/revisions and the downstream catalog
+generation observed by the current successful listing. The generation marker
+is request-local primitive evidence; it grants no cache acceptance or authority. Only immutable
+strings and numeric positions cross requests. Search views map positions to the
+current request's definitions after owner visibility, classification, redaction
+and endpoint restrictions; no query results are retained. Partial failed
+catalogs cannot enter this cache. Eviction changes cost only, never results.

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 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>` prefix the MCP instructions with `Use skills. ` and the description before routing rules; 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 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
@@ -2083,11 +2102,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 +2123,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 +2265,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 +2285,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 +2347,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,
@@ -2923,9 +2985,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`.