@zackbart/connecta 0.31.0 → 0.33.0

package/dist/registry.js

@@ -277,7 +277,7 @@ export class Registry {
                 throw new Error(`Connector "${c.id}" declares both staticTools and a classification; ` + "annotate static tools directly.");
             }
             this.connectors.set(c.id, c);
-            if (c.callAdmission) {
+            if (c.callAdmission !== undefined) {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
             }
         }
@@ -343,7 +343,7 @@ export class Registry {
         const requested = scope.connectorIds === "all" ? new Set(this.connectors.keys()) : new Set(scope.connectorIds);
         for (const id of requested) {
             if (!this.connectors.has(id)) {
-                throw new Error(`Identity access resolver returned unknown connector "${id}"`);
+                throw new Error(`Registry scope names unknown connector "${id}"`);
             }
         }
         return new ScopedRegistryView(this, requested, scope);
@@ -368,13 +368,13 @@ export class Registry {
                 this.warnedAbsentGrants.delete(oldest);
         }
         if (hasControlCharacters(toolName)) {
-            logFailure(this.opts.logger, "connectorAccess grant is unreachable", failureRecord({ connector: connectorId }));
+            logFailure(this.opts.logger, "pool tool grant is unreachable", failureRecord({ connector: connectorId }));
             return;
         }
         // Grant names are operator data but may carry any non-control character;
         // quote them so a line terminator a log reader honours cannot forge a line.
         const quoted = JSON.stringify(key).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
-        this.opts.logger.warn(`connectorAccess grants ${quoted} but connector "${connectorId}" lists no such tool; the grant is unreachable`);
+        this.opts.logger.warn(`a pool grants ${quoted} but connector "${connectorId}" lists no such tool; the grant is unreachable`);
     }
     async storeOAuthHandoff(connectorId, state, principalKey) {
         const key = oauthHandoffKeys.handoff(connectorId, await sha256Hex(state));
@@ -1005,13 +1005,13 @@ class ScopedRegistryView {
         return this.root.listConnectors().filter((connector) => this.registryFor(connector.id) !== undefined);
     }
     canReadConnectorSkills(id) {
-        return (this.registryFor(id) !== undefined && !this.scope.toolAccess?.has(id) && !this.scope.guardedToolAccess?.has(id));
+        return this.registryFor(id) !== undefined && !this.scope.toolAccess?.has(id);
     }
     getConnector(id) {
         return this.registryFor(id)?.getConnector(id);
     }
     getResourceConnector(id) {
-        if (this.scope.toolAccess?.has(id) || this.scope.guardedToolAccess?.has(id))
+        if (this.scope.toolAccess?.has(id))
             return undefined;
         return this.getConnector(id);
     }
@@ -1028,14 +1028,13 @@ class ScopedRegistryView {
             throw new Error(`Unknown connector "${args[0]}"`);
         }
         const tools = await registry.getTools(args[0], args[1], args[2], args[3], this.scope);
-        const guarded = this.scope.guardedToolAccess?.get(args[0]);
-        const granted = this.scope.toolAccess?.get(args[0]) ?? guarded;
+        const granted = this.scope.toolAccess?.get(args[0]);
         if (!granted)
             return tools;
         // Every consumer — search, describe, call_tool, and a program's
         // connecta.call — resolves through this list, so an ungranted tool is
         // indistinguishable from one the connector never had.
-        const visible = tools.filter((tool) => granted.has(tool.name) && (!guarded?.has(tool.name) || tool.classification === "read"));
+        const visible = tools.filter((tool) => granted.has(tool.name));
         if (visible.length < granted.size) {
             const present = new Set(tools.map((tool) => tool.name));
             for (const name of granted) {

package/dist/routes/access-tokens.js

@@ -1,62 +1,59 @@
-import { authorizeUiIdentity, isSameOrigin, privateJson } from "./shared.js";
-async function readName(request) {
-    if (!request.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
-        return {
-            ok: false,
-            response: privateJson({ error: "Content-Type must be application/json" }, { status: 415 }),
-        };
+import { AccessTokenError, isSlotRevision } from "../access-tokens.js";
+import { authorizeUiIdentity, boundedText, isSameOrigin, managesAgentTokens, privateJson, } from "./shared.js";
+/** The longest body, in characters, a token mutation accepts: `{ "expect": "<revision>" }` with room to spare. */
+const MAX_BODY_CHARS = 1_024;
+/**
+ * The slot revision a mutation names. POST takes it only as a JSON body,
+ * `{ "expect": "<revision>" }`; DELETE takes that body or, for clients that
+ * cannot send a body with DELETE, `?expect=<revision>`, but not both. Read
+ * only after the caller is authorized.
+ */
+async function expectedRevision(request) {
+    const query = new URL(request.url).searchParams.getAll("expect");
+    if (query.length > 0 && request.method !== "DELETE") {
+        return { status: 400, error: "expect belongs in the JSON body" };
     }
-    const reader = request.body?.getReader();
-    const chunks = [];
-    let size = 0;
-    if (reader) {
+    const raw = await boundedText(request, MAX_BODY_CHARS);
+    if (raw === undefined)
+        return { status: 413, error: "request body is too large" };
+    let candidate;
+    if (raw !== "") {
+        if (!request.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
+            return { status: 415, error: "Content-Type must be application/json" };
+        }
+        let body;
         try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                size += value.byteLength;
-                if (size > 1_000) {
-                    reader.cancel().catch(() => { });
-                    return { ok: false, response: privateJson({ error: "request body is too large" }, { status: 413 }) };
-                }
-                chunks.push(value);
-            }
+            body = JSON.parse(raw);
         }
-        finally {
-            reader.releaseLock();
+        catch {
+            return { status: 400, error: "invalid JSON body" };
         }
+        if (body === null || typeof body !== "object" || Array.isArray(body)) {
+            return { status: 400, error: "invalid JSON body" };
+        }
+        if (query.length > 0)
+            return { status: 400, error: "give expect once, in the body or the query" };
+        candidate = body.expect;
     }
-    const bytes = new Uint8Array(size);
-    let offset = 0;
-    for (const chunk of chunks) {
-        bytes.set(chunk, offset);
-        offset += chunk.byteLength;
-    }
-    const raw = new TextDecoder().decode(bytes);
-    if (raw.length > 1_000) {
-        return {
-            ok: false,
-            response: privateJson({ error: "request body is too large" }, { status: 413 }),
-        };
-    }
-    try {
-        const body = JSON.parse(raw);
-        return { ok: true, name: body.name };
+    else if (query.length === 1) {
+        candidate = query[0];
     }
-    catch {
-        return {
-            ok: false,
-            response: privateJson({ error: "invalid JSON body" }, { status: 400 }),
-        };
+    if (candidate === undefined) {
+        return { status: 400, error: "expect is required: the slot revision from GET /ui/access-tokens" };
     }
+    return isSlotRevision(candidate) ? { expect: candidate } : { status: 400, error: "expect is not a slot revision" };
 }
 /**
- * Interactive-operator lifecycle for deployment access tokens. The token itself
+ * Interactive-operator lifecycle for agent tokens: list one slot per declared
+ * agent, issue or rotate its token, and revoke it. Each mutation names the
+ * slot revision it decided from, so a stale view refuses with 409
+ * `slot_changed` instead of issuing over a token or rotating over someone
+ * else's fresh rotation. Agents themselves come only
+ * from code, so nothing here creates, renames, or rebinds one. The token itself
  * is deliberately never an administrator credential and cannot reach here.
  */
 export async function routeAccessTokens(context, manager) {
-    const match = /^\/ui\/access-tokens(?:\/([0-9a-f-]{36}))?$/.exec(context.path);
+    const match = /^\/ui\/access-tokens(?:\/([a-z0-9_-]{1,64}))?$/.exec(context.path);
     if (!match)
         return null;
     const { request, baseUrl, opts } = context;
@@ -67,41 +64,51 @@ export async function routeAccessTokens(context, manager) {
     if (mutating && !isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiIdentity(request, baseUrl, opts.config.auth, "access token management", context.runtimeContext, opts.config.identity);
+    const admin = await authorizeUiIdentity(request, baseUrl, opts.config.auth, "access token management", context.runtimeContext);
     if (!admin.ok)
         return admin.response;
-    if (!admin.accessTokenManagement || !admin.identity.principal) {
-        return privateJson({ error: "access token management permission required" }, { status: 403 });
+    // Interactive maintainers alone manage agent tokens (#837); anyone else
+    // gets the same private 404 every operator route gives them.
+    if (!managesAgentTokens(opts, admin) || !admin.identity.principal) {
+        return privateJson({ error: "not found" }, { status: 404 });
     }
-    const id = match[1];
+    const operator = `${admin.identity.principal.namespace}:${admin.identity.principal.id}`;
+    const name = match[1];
     try {
-        if (!id && request.method === "GET") {
-            return privateJson({ accessTokens: await manager.list() });
+        if (!name && request.method === "GET") {
+            return privateJson({ agents: await manager.list() });
         }
-        if (!id && request.method === "POST") {
-            const input = await readName(request);
-            if (!input.ok)
-                return input.response;
-            return privateJson(await manager.create(input.name, admin.identity.principal), { status: 201 });
+        if (!name || (request.method !== "POST" && request.method !== "DELETE")) {
+            return privateJson({ error: "method not allowed" }, { status: 405 });
         }
-        if (id && request.method === "PUT") {
-            const input = await readName(request);
-            if (!input.ok)
-                return input.response;
-            const accessToken = await manager.rename(id, input.name);
-            return accessToken
-                ? privateJson({ accessToken })
-                : privateJson({ error: "unknown access token" }, { status: 404 });
+        const expected = await expectedRevision(request);
+        if (!("expect" in expected))
+            return privateJson({ error: expected.error }, { status: expected.status });
+        // The request's signal bounds each mutation: a caller that leaves before
+        // the slot commit publishes nothing, and one that leaves after a rotation
+        // commits has the slot revoked, since its secret cannot be delivered.
+        const options = { signal: request.signal, expect: expected.expect };
+        if (request.method === "POST")
+            return privateJson(await manager.rotate(name, operator, options));
+        return privateJson({ agent: await manager.revoke(name, options) });
+    }
+    catch (error) {
+        if (error instanceof AccessTokenError && error.code === "unknown_agent") {
+            return privateJson({ error: "unknown agent" }, { status: 404 });
         }
-        if (id && request.method === "DELETE") {
-            const accessToken = await manager.revoke(id, `${admin.identity.principal.namespace}:${admin.identity.principal.id}`);
-            return accessToken
-                ? privateJson({ accessToken })
-                : privateJson({ error: "unknown access token" }, { status: 404 });
+        if (error instanceof AccessTokenError && error.code === "aborted") {
+            return privateJson({ error: "request ended" }, { status: 499 });
         }
-        return privateJson({ error: "method not allowed" }, { status: 405 });
-    }
-    catch {
-        return privateJson({ error: "Access token operation failed; check the name, capacity, and storage" }, { status: 400 });
+        if (error instanceof AccessTokenError && error.code === "outcome_unknown") {
+            // A fixed, operation-specific sentence; it never carries storage text.
+            return privateJson({ error: error.message }, { status: 503 });
+        }
+        if (error instanceof AccessTokenError && error.code === "slot_changed") {
+            return privateJson({ error: "The agent's token slot changed; reload and retry", code: "slot_changed" }, { status: 409 });
+        }
+        if (error instanceof AccessTokenError && error.code === "conflict") {
+            return privateJson({ error: "The agent's token changed meanwhile; reload and retry" }, { status: 409 });
+        }
+        return privateJson({ error: "Access token operation failed; check storage" }, { status: 400 });
     }
 }

package/dist/routes/activity-disclosure.js

@@ -1,23 +1,22 @@
-import { intersectAccess } from "../connector-access.js";
 import { recordedToolName } from "../operator-record.js";
-/** Historical disclosure uses the verdict at call time; old guarded rows fail closed. */
-function activityToolVisible(authz, event) {
-    const allowed = authz.toolAccess?.get(event.connectorId);
-    return (recordedToolName({ name: event.toolName }) === event.toolName &&
-        (!allowed || allowed.has(event.toolName)) &&
-        (!authz.guardedToolAccess?.get(event.connectorId)?.has(event.toolName) || event.classification === "read"));
+/** A recorded tool is shown only when its name passes the record grammar and its endpoint granted it. */
+function activityToolVisible(access, event) {
+    const allowed = access.toolAccess?.get(event.connectorId);
+    return recordedToolName({ name: event.toolName }) === event.toolName && (!allowed || allowed.has(event.toolName));
 }
 /**
- * One disclosure rule for the timeline and the UI's last-call overlay.
- * After Activity access and the read gate, operators and activityAccess machine
- * callers may see other principals' shared-connector history when connector/tool
- * and recorded-pool grants permit, including request IDs, client name/version,
- * and actor kind/id/namespace. Interactive reads may add directory actor labels;
- * machine reads do not. Personal history requires a matching principal owner.
+ * One disclosure rule for the timeline and the UI's last-call overlay. Only
+ * maintainers read activity (#837), and only after the optional
+ * read gate. They may see other principals' shared-connector history,
+ * including request IDs, client name/version, and actor kind/id/namespace, on
+ * plain /mcp and in every declared pool, within the tools that pool declares.
+ * Interactive reads may add directory actor labels; machine reads do not.
+ * Personal history requires a matching principal owner. A row recorded in a
+ * pool that is no longer declared is withheld.
  */
-export function activityEventVisible(context, authz, registry, admittedPools, event) {
+export function activityEventVisible(context, authz, registry, event) {
     const connector = registry.getConnector(event.connectorId);
-    if (!connector || (event.pool !== undefined && !admittedPools.has(event.pool)))
+    if (!connector)
         return false;
     if (connector.authScope === "personal" || (event.kind === "catalog_drift" && event.actorBasis === "principal")) {
         const owner = authz.identity.principal;
@@ -27,10 +26,10 @@ export function activityEventVisible(context, authz, registry, admittedPools, ev
             event.actor.namespace !== owner.namespace)
             return false;
     }
-    const pool = event.pool ? context.opts.pools.get(event.pool) : undefined;
-    if (event.pool && !pool)
+    const pool = event.pool !== undefined ? context.opts.pools.get(event.pool) : undefined;
+    if (event.pool !== undefined && !pool)
         return false;
-    const access = pool ? intersectAccess(authz, pool.access) : authz;
+    const access = pool ? pool.access : { connectorIds: "all" };
     if (access.connectorIds !== "all" && !access.connectorIds.includes(event.connectorId))
         return false;
     // Connector-wide counts reveal tools outside an address-only grant.

package/dist/routes/activity.js

@@ -1,10 +1,10 @@
 import { activityEventVisible } from "./activity-disclosure.js";
-import { Duration, Effect } from "effect";
+import { Effect } from "effect";
 import { activityBehaviorFacts, activityPackageVersion, activityClientFact, InvalidActivityCursorError, } from "../activity.js";
 import { failureRecord, logFailure } from "../operator-record.js";
-import { ACTOR_LABEL_BUDGET_MS, ACTOR_LABEL_CONCURRENCY, actorKey, cleanActorLabel, labelLookups, } from "./actor-labels.js";
+import { actorKey, resolveActorLabels } from "./actor-labels.js";
 import { authorized, refuse, serveOperator, visibleRegistry } from "./operator.js";
-import { privateJson } from "./shared.js";
+import { privateJson, readsActivity } from "./shared.js";
 /**
  * Add display-only actor labels to one authorized activity page. Resolution is
  * best-effort, bounded, and read-time only: stored events retain stable ids and
@@ -15,50 +15,42 @@ import { privateJson } from "./shared.js";
  * abandoned, as they are when the reader leaves.
  */
 function enrichActivityActorLabels(page, auth) {
-    return Effect.suspend(() => {
-        const labels = new Map();
-        const resolve = ({ key, id, provider }) => Effect.tryPromise(() => Promise.resolve(provider.activityActorLabel(id))).pipe(Effect.map(cleanActorLabel), Effect.orElseSucceed(() => undefined), Effect.map((label) => {
-            if (label)
-                labels.set(key, label);
-        }));
-        return Effect.forEach(labelLookups(page.events.map((event) => event.actor), auth), resolve, {
-            concurrency: ACTOR_LABEL_CONCURRENCY,
-            discard: true,
-        }).pipe(Effect.timeoutOption(Duration.millis(ACTOR_LABEL_BUDGET_MS)), Effect.map(() => ({
-            ...page,
-            events: page.events.map((event) => {
-                const resolved = event.actor.id ? labels.get(actorKey(event.actor)) : undefined;
-                // Never trust or echo a `label` supplied by storage. The persisted event
-                // schema has no label; only this authenticated read path may add one.
-                const actor = {
-                    kind: event.actor.kind,
-                    ...(event.actor.id ? { id: event.actor.id } : {}),
-                    ...(event.actor.namespace ? { namespace: event.actor.namespace } : {}),
-                };
-                // Re-check stored client facts, including custom readers and old rows.
-                const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, pool: _pool, actorBasis: _actorBasis, ...record } = event;
-                const packageVersion = activityPackageVersion(suppliedPackageVersion);
-                const clientName = activityClientFact(suppliedName, "name");
-                const clientVersion = activityClientFact(suppliedVersion, "version");
-                return {
-                    ...record,
-                    ...activityBehaviorFacts(event),
-                    ...(packageVersion !== undefined ? { packageVersion } : {}),
-                    ...(clientName !== undefined ? { clientName } : {}),
-                    ...(clientVersion !== undefined ? { clientVersion } : {}),
-                    actor: resolved ? { ...actor, label: resolved } : actor,
-                };
-            }),
-        })));
-    });
+    return resolveActorLabels(page.events.map((event) => event.actor), auth).pipe(Effect.map((labels) => ({
+        ...page,
+        events: page.events.map((event) => {
+            const resolved = event.actor.id ? labels.get(actorKey(event.actor)) : undefined;
+            // Never trust or echo a `label` supplied by storage. The persisted event
+            // schema has no label; only this authenticated read path may add one.
+            const actor = {
+                kind: event.actor.kind,
+                ...(event.actor.id ? { id: event.actor.id } : {}),
+                ...(event.actor.namespace ? { namespace: event.actor.namespace } : {}),
+            };
+            // Re-check stored client facts, including custom readers and old rows.
+            const { packageVersion: suppliedPackageVersion, clientName: suppliedName, clientVersion: suppliedVersion, classification: _classification, resultBytes: _resultBytes, kind: _kind, drift: _drift, pool: _pool, actorBasis: _actorBasis, ...record } = event;
+            const packageVersion = activityPackageVersion(suppliedPackageVersion);
+            const clientName = activityClientFact(suppliedName, "name");
+            const clientVersion = activityClientFact(suppliedVersion, "version");
+            return {
+                ...record,
+                ...activityBehaviorFacts(event),
+                ...(packageVersion !== undefined ? { packageVersion } : {}),
+                ...(clientName !== undefined ? { clientName } : {}),
+                ...(clientVersion !== undefined ? { clientVersion } : {}),
+                actor: resolved ? { ...actor, label: resolved } : actor,
+            };
+        }),
+    })));
 }
 function activityRead(context) {
     const { url, opts } = context;
     return Effect.gen(function* () {
         const authz = yield* authorized(context);
+        // A maintainer principal, interactive or not (#837); members and agents
+        // get the private 404 every operator route gives them.
+        if (!readsActivity(context.opts, authz))
+            return yield* refuse("not found", 404);
         const registry = yield* visibleRegistry(context, authz);
-        if (!authz.operator)
-            return yield* refuse("activity access required", 403);
         if (opts.config.activity?.readGate &&
             !(yield* Effect.promise(async () => opts.config.activity?.readGate(authz.actor)))) {
             return yield* refuse("forbidden", 403);
@@ -66,19 +58,7 @@ function activityRead(context) {
         const list = opts.config.activity?.store.list?.bind(opts.config.activity?.store);
         if (!list)
             return yield* refuse("activity history is not configured", 404);
-        const admittedPools = new Set();
-        for (const [name, pool] of opts.pools) {
-            if (yield* Effect.promise(async () => {
-                try {
-                    return (await pool.grant(authz.identity)) === true;
-                }
-                catch {
-                    return false;
-                }
-            }))
-                admittedPools.add(name);
-        }
-        const visible = (event) => activityEventVisible(context, authz, registry, admittedPools, event);
+        const visible = (event) => activityEventVisible(context, authz, registry, event);
         const cursor = url.searchParams.get("cursor") ?? undefined;
         if (cursor && cursor.length > 500)
             return yield* refuse("invalid cursor", 400);

package/dist/routes/actor-labels.js

@@ -2,11 +2,12 @@
 // read time from the one auth provider that owns the actor's directory, and
 // only on an authorized read path. Nothing here is persisted, and a label a
 // store happens to carry is never trusted or echoed.
+import { Duration, Effect } from "effect";
 import { activityActorNamespace } from "./shared.js";
-export const ACTOR_LABEL_CONCURRENCY = 8;
-export const ACTOR_LABEL_BUDGET_MS = 1_500;
+const ACTOR_LABEL_CONCURRENCY = 8;
+const ACTOR_LABEL_BUDGET_MS = 1_500;
 const ACTOR_LABEL_MAX_LENGTH = 160;
-export function cleanActorLabel(value) {
+function cleanActorLabel(value) {
     if (typeof value !== "string")
         return undefined;
     const compact = value.replace(/\s+/gu, " ").trim();
@@ -22,7 +23,7 @@ export function actorKey(actor) {
  * the actor's directory. An actor no provider can claim unambiguously gets no
  * lookup at all.
  */
-export function labelLookups(actors, auth) {
+function labelLookups(actors, auth) {
     const identities = new Map();
     for (const actor of actors) {
         if (!actor.id)
@@ -65,3 +66,31 @@ export function labelLookups(actors, auth) {
     }
     return lookups;
 }
+/**
+ * Resolve labels for these actors, keyed by `actorKey`. Best-effort and
+ * bounded: at most eight lookups run at once, and whatever has resolved
+ * within 1.5 seconds in all is used; the rest are abandoned, as they are when
+ * the reader leaves. A lookup that fails or answers nothing usable is absent.
+ */
+export function resolveActorLabels(actors, auth) {
+    return Effect.suspend(() => {
+        const labels = new Map();
+        const resolve = ({ key, id, provider }) => Effect.tryPromise(() => Promise.resolve(provider.activityActorLabel(id))).pipe(Effect.map(cleanActorLabel), Effect.orElseSucceed(() => undefined), Effect.map((label) => {
+            if (label)
+                labels.set(key, label);
+        }));
+        return Effect.forEach(labelLookups(actors, auth), resolve, {
+            concurrency: ACTOR_LABEL_CONCURRENCY,
+            discard: true,
+        }).pipe(Effect.timeoutOption(Duration.millis(ACTOR_LABEL_BUDGET_MS)), Effect.map(() => labels));
+    });
+}
+/**
+ * The activity actor a listed person would be recorded as: the principal in
+ * the namespace of the interactive provider that owns that directory. People
+ * no interactive provider owns have no actor, and so no label.
+ */
+export function principalActor(principal, auth) {
+    const provider = auth.find((candidate) => candidate.interactiveOperator && activityActorNamespace(candidate) === principal.namespace);
+    return provider ? { kind: provider.kind, id: principal.id, namespace: principal.namespace } : undefined;
+}

package/dist/routes/agent-path.js

@@ -0,0 +1,43 @@
+// Agent endpoint paths (#837, decisions/0006). Cloudflare Access bypasses
+// `/agent/*` at the edge after resolving dot segments, folding case, decoding
+// unreserved escapes, and collapsing a leading `//`, while the Worker sees
+// the raw pathname. So connecta claims every path Access might treat as
+// `/agent/*`, and admits only the one exact, raw spelling of a pool.
+/** Pool names, as `createConnecta` validates them. */
+const POOL_NAME_RE = /^[a-z0-9_-]+$/;
+/** Escapes decoded before giving up and treating the path as an agent path. */
+const MAX_DECODE_ROUNDS = 8;
+/**
+ * The pool an agent endpoint names, or undefined. The raw pathname must be
+ * byte-equal to `/agent/` plus a well-formed pool name: no decoding, case
+ * folding, slash collapsing, trailing slash, extra segment, or `%`.
+ */
+export function agentEndpointPool(path) {
+    if (!path.startsWith("/agent/"))
+        return undefined;
+    const pool = path.slice("/agent/".length);
+    return POOL_NAME_RE.test(pool) ? pool : undefined;
+}
+/**
+ * Whether a pathname belongs to the agent namespace: anything that starts
+ * with `/agent` once every escape is decoded, case is folded, and slashes are
+ * collapsed. This is deliberately wider than Access's own matching, so no
+ * path the edge bypasses can fall through to a human route.
+ */
+export function isAgentPath(path) {
+    let value = path;
+    for (let round = 0; value.includes("%"); round++) {
+        // Still encoded after the bound: refuse it with the agent 404.
+        if (round === MAX_DECODE_ROUNDS)
+            return true;
+        const decoded = value.replace(/%([0-9a-f]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+        if (decoded === value)
+            break;
+        value = decoded;
+    }
+    return value
+        .replace(/\\/g, "/")
+        .replace(/\/{2,}/g, "/")
+        .toLowerCase()
+        .startsWith("/agent");
+}

package/dist/routes/connect.js

@@ -8,7 +8,7 @@ import { drainOAuthStartResets } from "../auth/oauth-start-reset.js";
 import { finishOAuthConnectStart, consumeOAuthConnectLink, oauthConnectUnavailable, verifyOAuthHandoff, } from "../oauth-handoff.js";
 import { failureRecord, logFailure } from "../operator-record.js";
 import { runEdge, withDeadlineEffect } from "../runtime/run.js";
-import { authorizeUiIdentity, mayManageConnector, privateJson, validateAuthPermissions, withSessionCookies, } from "./shared.js";
+import { admitsMaintainer, authorizeUiIdentity, mayManageConnector, privateJson, withSessionCookies, } from "./shared.js";
 const START_TIMEOUT_MS = 30_000;
 /** Clerk establishes a browser session on this origin before retrying the link. */
 function clerkSignIn(context) {
@@ -84,33 +84,37 @@ async function connect(context) {
             headers: { Location: target.href, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" },
         });
     };
-    const authz = await authorizeUiIdentity(request, baseUrl, opts.config.auth, "OAuth connection", runtimeContext, opts.config.identity);
+    const authz = await authorizeUiIdentity(request, baseUrl, opts.config.auth, "OAuth connection", runtimeContext);
     if (!authz.ok) {
         // Access sign-in is enforced at the edge. Clerk needs its own sign-in page.
+        // The sign-in page returns to this link, which then sends a maintainer on
+        // to the operator UI. Pool members cannot use that UI yet (#837), so
+        // signing in there would strand them.
         if (authz.response.status === 401 &&
             authorizationCredential(request).kind === "absent" &&
             !runtimeContext?.access) {
-            if (opts.config.ui)
-                return authPage();
             const signIn = clerkSignIn(context);
             if (signIn)
                 return signIn;
+            if (opts.config.ui)
+                return authPage();
         }
         return authz.response;
     }
-    try {
-        validateAuthPermissions(authz, opts.registry);
-    }
-    catch {
-        return refuse("forbidden");
-    }
     const connector = opts.registry.getConnector(id);
-    if (authz.principalKey !== handoff.principal || !mayManageConnector(authz, connector)) {
+    // Visibility is the caller's pools, or everything for a maintainer, so a
+    // member may connect a personal connector in a pool they belong to.
+    if (authz.principalKey !== handoff.principal || !mayManageConnector(opts, authz, connector)) {
         return refuse("Sign in as the user who requested this connection and has permission to manage it.");
     }
+    // The operator UI serves maintainers only until member views ship (#837).
+    // A member's OAuth link starts here directly, as it does without a UI.
+    const viaUi = Boolean(opts.config.ui) && admitsMaintainer(opts, authz);
     if (!connector.startAuth) {
         if (!connector.credential || !opts.config.ui || !opts.config.vault)
             return refuse("unknown OAuth connector", 404);
+        if (!viaUi)
+            return refuse("Credential entry is in the operator UI, which only maintainers can use for now.");
         let target;
         try {
             target = new URL(opts.config.ui.credentialHandoffUrl(baseUrl), baseUrl);
@@ -133,7 +137,7 @@ async function connect(context) {
             },
         }), authz.sessionCookies);
     }
-    if (opts.config.ui && context.url.searchParams.get("start") !== "1")
+    if (viaUi && context.url.searchParams.get("start") !== "1")
         return withSessionCookies(authPage(), authz.sessionCookies);
     const registry = opts.registry.scoped({
         connectorIds: [id],