@zackbart/connecta 0.31.0 → 0.33.0

package/dist/routes/shared.d.ts

@@ -1,10 +1,10 @@
 import type { ActivityActor } from "../activity.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
-import type { Registry, ToolAccess } from "../registry.js";
-import type { ResolvedPool } from "../connector-access.js";
-import type { AuthenticatedIdentity, Executor, InboundAuth, InboundAuthRuntimeContext } from "../types.js";
-import type { ConnectorPermission, ConnectaIdentityConfig, ResolvedConfig } from "../config.js";
+import type { Registry } from "../registry.js";
+import { type ResolvedPool } from "../membership.js";
+import type { AuthenticatedIdentity, Executor, IdentityReference, InboundAuth, InboundAuthRuntimeContext } from "../types.js";
+import type { ResolvedConfig } from "../config.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
     /**
@@ -17,6 +17,8 @@ export interface ServerOptions {
     configDescription: import("../describe-config.js").ConnectaConfigDescription;
     configValueSources?: Readonly<Record<string, "default" | "config">>;
     registry: Registry;
+    /** Resolved `maintainers`: the only principals plain `/mcp` and operator routes admit. */
+    maintainers: readonly IdentityReference[];
     /** Validated named pools served at `/mcp/<name>`; empty when none declared. */
     pools: ReadonlyMap<string, ResolvedPool>;
     /** Required sandbox backing execute_code, wrapped in fallback admission if needed. */
@@ -39,6 +41,14 @@ export interface RouteContext {
     runtimeContext: RuntimeExecutionContext | undefined;
 }
 export declare function privateJson(body: unknown, init?: ResponseInit): Response;
+/**
+ * The body as text, or undefined once it is longer than `maxChars`. No UTF-16
+ * unit costs more than three bytes, and a malformed sequence decodes to one
+ * U+FFFD per at most three bytes, so a body past three bytes per character is
+ * past the limit too — and reading stops there, instead of buffering whatever
+ * a client cares to send before measuring it.
+ */
+export declare function boundedText(request: Request, maxChars: number): Promise<string | undefined>;
 /**
  * Bounded, escaped form of a caller-influenced value (an identity id or OAuth
  * callback connector id) for the operator log. Goes
@@ -55,40 +65,70 @@ export declare function authMetadata(request: Request, baseUrl: string, auth: re
     provider: InboundAuth;
     response: Response;
 } | null>;
-export declare function authorize(request: Request, baseUrl: string, auth: readonly InboundAuth[], runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig, partitionIdentity?: boolean, interactiveOnly?: boolean): Promise<{
+export declare function authorize(request: Request, baseUrl: string, auth: readonly InboundAuth[], runtimeContext?: RuntimeExecutionContext, partitionIdentity?: boolean, interactiveOnly?: boolean): Promise<{
     ok: true;
     actor: ActivityActor;
     identity: AuthenticatedIdentity;
     sessionCookies?: readonly string[];
     subjectKey?: string;
     principalKey?: string;
-    connectorIds: "all" | readonly string[];
-    /** Per-connector tool allowlist for connectors granted by address only. */
-    toolAccess?: ToolAccess;
-    /** Granted addresses that still require the catalog's read-only hint. */
-    guardedToolAccess?: ToolAccess;
-    operator: boolean;
-    accessTokenManagement: boolean;
-    credentialAdministration: ConnectorPermission;
-    personalConnection: ConnectorPermission;
-    /** Backward-compatible name used by operator views. */
-    uiAdminEligible?: boolean;
 } | {
     ok: false;
     response: Response;
 }>;
+/**
+ * Admission at an agent endpoint, `/agent/<pool>` (#837). Only the built-in
+ * `cta_` adapter is consulted: Clerk and Access never run, cookies and Clerk
+ * handshake parameters are stripped, and the runtime context, which carries
+ * Access's `ctx.access` even on a bypassed path, is never passed. Anything but
+ * an admitted declared agent gets the machine-only challenge.
+ */
+export declare function authorizeAgent(request: Request, baseUrl: string, auth: readonly InboundAuth[]): Promise<Awaited<ReturnType<typeof authorize>>>;
 /** Human routes reject machine credentials before any verification or storage I/O. */
-export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: readonly InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<Awaited<ReturnType<typeof authorize>>>;
+export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: readonly InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext): Promise<Awaited<ReturnType<typeof authorize>>>;
 export declare function isSameOrigin(request: Request, baseUrl: string): boolean;
 export declare function withSecurityHeaders(response: Response, requestUrl: URL, _path: string): Response;
 type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
     ok: true;
 }>;
-/** Unknown configured ids refuse the complete view, including management rights. */
-export declare function validateAuthPermissions(authz: AuthorizedIdentity, registry: Registry): void;
-export declare function mayManageConnector(authz: AuthorizedIdentity, connector: {
+/**
+ * Plain `/mcp` and every operator route admit a maintainer (#837). An open
+ * deployment has no inbound auth and so no maintainers: its one anonymous
+ * caller keeps the whole default endpoint, as the startup warning says.
+ */
+export declare function admitsMaintainer(opts: ServerOptions, authz: AuthorizedIdentity): boolean;
+/**
+ * The declared pool `/mcp/<name>` serves to this person, or undefined for the
+ * same 404. An agent is never admitted here, even when listed (#837).
+ */
+export declare function memberPool(opts: ServerOptions, name: string, identity: Readonly<AuthenticatedIdentity>): ResolvedPool | undefined;
+/** The declared pool `/agent/<name>` serves to this agent, or undefined for the same 404. */
+export declare function agentPool(opts: ServerOptions, name: string, identity: Readonly<AuthenticatedIdentity>): ResolvedPool | undefined;
+/**
+ * The connectors of every pool this identity is a member of (#837): what a
+ * pool member may ever manage, and only their personal ones among these.
+ */
+export declare function memberConnectors(opts: ServerOptions, identity: Readonly<AuthenticatedIdentity>): "all" | ReadonlySet<string>;
+/**
+ * Whether this identity may start, finish, or remove a connector's auth
+ * (#837). Only an interactive person ever may; an agent or any other machine
+ * credential manages nothing. Shared auth is deployment-wide, so it takes a
+ * maintainer. A personal connector takes a stable principal that is a
+ * maintainer, whose plain `/mcp` includes it, or a member of a pool that
+ * contains it; either way it is always the caller's own partition, which
+ * callers bind by principal. Every path that issues a link, starts,
+ * completes, or disconnects auth, or writes a credential, asks this.
+ */
+export declare function mayManageConnector(opts: ServerOptions, authz: AuthorizedIdentity, connector: {
     id: string;
     authScope?: "shared" | "personal";
 }): boolean;
+/** Agent token list, issue, rotate, and revoke: an interactive maintainer only (#837). */
+export declare function managesAgentTokens(opts: ServerOptions, authz: AuthorizedIdentity): boolean;
+/**
+ * Activity reads: a maintainer principal, interactive or not (#837). Members
+ * and agents read none, and an open deployment has no maintainer.
+ */
+export declare function readsActivity(opts: ServerOptions, authz: AuthorizedIdentity): boolean;
 /** Preserve refreshed browser cookies on the redirect or completion page. */
 export declare function withSessionCookies(response: Response, cookies?: readonly string[]): Response;

package/dist/routes/shared.js

@@ -1,7 +1,8 @@
 import { authorizationCredential, authorizationRequest, isMachineCredential } from "../inbound-credential.js";
 import { htmlSecurityHeaders } from "../html-security.js";
-import { parseConnectorAccess } from "../connector-access.js";
+import { isMaintainer, isMember } from "../membership.js";
 import { identityStorageKey, validIdentityReference } from "../identity.js";
+import { assertsAgents, isAgentName } from "../agent-identity.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
@@ -10,6 +11,40 @@ export function privateJson(body, init = {}) {
     headers.set("Referrer-Policy", "no-referrer");
     return new Response(JSON.stringify(body), { ...init, headers });
 }
+/**
+ * The body as text, or undefined once it is longer than `maxChars`. No UTF-16
+ * unit costs more than three bytes, and a malformed sequence decodes to one
+ * U+FFFD per at most three bytes, so a body past three bytes per character is
+ * past the limit too — and reading stops there, instead of buffering whatever
+ * a client cares to send before measuring it.
+ */
+export async function boundedText(request, maxChars) {
+    if (!request.body)
+        return "";
+    const maxBytes = maxChars * 3;
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            reader.cancel().catch(() => { });
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    const text = new TextDecoder().decode(bytes);
+    return text.length > maxChars ? undefined : text;
+}
 const MAX_LOGGED_VALUE_LENGTH = 64;
 /**
  * Bounded, escaped form of a caller-influenced value (an identity id or OAuth
@@ -42,6 +77,13 @@ export async function authMetadata(request, baseUrl, auth) {
     return null;
 }
 async function providerChallenge(response, request, baseUrl, auth, refusingProvider) {
+    const privateHeaders = new Headers(response.headers);
+    privateHeaders.set("Cache-Control", "no-store");
+    response = new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: privateHeaders,
+    });
     if (response.status !== 401)
         return response;
     if (!response.headers.has("WWW-Authenticate")) {
@@ -80,7 +122,7 @@ function recognizedProvider(request, auth, runtimeContext) {
     }
     return undefined;
 }
-export async function authorize(request, baseUrl, auth, runtimeContext, identityConfig, partitionIdentity = true, interactiveOnly = false) {
+export async function authorize(request, baseUrl, auth, runtimeContext, partitionIdentity = true, interactiveOnly = false) {
     const credential = authorizationCredential(request);
     const explicit = credential.kind !== "absent";
     if (credential.kind === "invalid") {
@@ -100,56 +142,53 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
     if (interactiveOnly && machineCredential) {
         return { ok: false, response: privateJson({ error: "authenticated user required" }, { status: 403 }) };
     }
+    // Every caller of this function is a human route. Agents reach pools only at
+    // `/agent/<pool>` (#837), so a `cta_` token refuses here without consulting
+    // token storage, and never falls back to a cookie, session, or Access context.
+    if (machineCredential) {
+        return {
+            ok: false,
+            response: await providerChallenge(privateJson({ error: "unauthorized" }, {
+                status: 401,
+                headers: { "WWW-Authenticate": "Bearer" },
+            }), request, baseUrl, auth),
+        };
+    }
     if (auth.length === 0 && !interactiveOnly && !explicit) {
         const actor = { kind: "anonymous" };
         const identity = { actor, interactive: false };
-        let access;
-        try {
-            access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all", { allowReadOnly: true });
-        }
-        catch {
-            return {
-                ok: false,
-                response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
-            };
-        }
-        return {
-            ok: true,
-            actor,
-            identity,
-            ...access,
-            operator: false,
-            accessTokenManagement: false,
-            credentialAdministration: "none",
-            personalConnection: "none",
-        };
+        return { ok: true, actor, identity };
     }
+    // The built-in agent adapter answers only agent endpoints. A deployment
+    // whose only provider is that adapter still refuses here, never opens.
+    const humanAuth = auth.filter((provider) => !assertsAgents(provider));
     let recognized;
     try {
-        recognized = recognizedProvider(request, machineCredential ? auth.filter((provider) => provider.kind === "access_token") : auth, runtimeContext);
+        recognized = recognizedProvider(request, humanAuth, runtimeContext);
     }
     catch {
         return { ok: false, response: privateJson({ error: "credential recognition failed" }, { status: 403 }) };
     }
-    if (machineCredential && !recognized) {
-        return {
-            ok: false,
-            response: await providerChallenge(privateJson({ error: "unauthorized" }, {
-                status: 401,
-                headers: { "WWW-Authenticate": "Bearer" },
-            }), request, baseUrl, auth),
-        };
-    }
     if (interactiveOnly && recognized && !recognized.interactiveOperator) {
         return { ok: false, response: privateJson({ error: "authenticated user required" }, { status: 403 }) };
     }
     let lastResponse = null;
-    const eligible = auth.filter((provider) => (!interactiveOnly || provider.interactiveOperator) &&
-        (!explicit || machineCredential || provider.kind !== "access_token" || !provider.recognizesCredential));
+    const eligible = humanAuth.filter((provider) => (!interactiveOnly || provider.interactiveOperator) &&
+        (!explicit || provider.kind !== "access_token" || !provider.recognizesCredential));
     // A header owns one verdict even for adapters without a recognition hook.
     const candidates = recognized ? [recognized] : explicit ? eligible.slice(0, 1) : eligible;
     for (const provider of candidates) {
         const result = await provider.authorize(request, baseUrl, runtimeContext);
+        // Only the built-in access-token adapter asserts an agent, and it never
+        // answers here. Any `agent` claim refuses like an unknown token.
+        const agent = result.ok ? result.agent : undefined;
+        if (result.ok && agent !== undefined) {
+            lastResponse = privateJson({ error: "unauthorized" }, {
+                status: 401,
+                headers: { "WWW-Authenticate": "Bearer" },
+            });
+            break;
+        }
         if (result.ok) {
             if (interactiveOnly && !result.userId) {
                 return { ok: false, response: privateJson({ error: "authenticated user required" }, { status: 403 }) };
@@ -164,7 +203,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             const interactive = Boolean(result.userId && provider.interactiveOperator);
             // Principal-only API callers still need a stable typed actor for history
             // ownership. Never collapse distinct personal partitions into { kind }.
-            const actorId = subjectId ?? principal?.id;
+            const actorId = agent ?? subjectId ?? principal?.id;
             const recordNamespace = actorNamespace ?? (subjectId === undefined ? principal?.namespace : undefined);
             const actor = {
                 kind: provider.kind,
@@ -175,48 +214,9 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 actor,
                 ...(subject ? { subject } : {}),
                 ...(principal ? { principal } : {}),
+                ...(agent !== undefined ? { agent } : {}),
                 interactive,
             };
-            let operator = interactive;
-            let accessTokenManagement = false;
-            let credentialAdministration = "none";
-            let personalConnection = "none";
-            let access;
-            try {
-                if (identityConfig?.activityAccess) {
-                    operator = principal ? await identityConfig.activityAccess(principal) : false;
-                }
-                access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all", { allowReadOnly: true });
-                if (interactive) {
-                    accessTokenManagement = identityConfig?.accessTokenManagement
-                        ? await identityConfig.accessTokenManagement(identity)
-                        : false;
-                    if (typeof accessTokenManagement !== "boolean")
-                        throw new Error("invalid token management permission");
-                    credentialAdministration = identityConfig?.credentialAdministration
-                        ? await identityConfig.credentialAdministration(identity)
-                        : "none";
-                    personalConnection =
-                        principal && identityConfig?.personalConnection
-                            ? await identityConfig.personalConnection(identity)
-                            : "none";
-                }
-                if (typeof operator !== "boolean")
-                    throw new Error("invalid activity permission");
-                for (const permission of [credentialAdministration, personalConnection]) {
-                    if (permission !== "all" &&
-                        permission !== "none" &&
-                        (!Array.isArray(permission) ||
-                            !permission.every((id) => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
-                        throw new Error("invalid identity permission");
-                }
-            }
-            catch {
-                return {
-                    ok: false,
-                    response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
-                };
-            }
             return {
                 ok: true,
                 actor,
@@ -224,12 +224,6 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 ...(result.sessionCookies?.length ? { sessionCookies: result.sessionCookies } : {}),
                 ...(subject && partitionIdentity ? { subjectKey: await identityStorageKey(subject) } : {}),
                 ...(principal && partitionIdentity ? { principalKey: await identityStorageKey(principal) } : {}),
-                ...access,
-                accessTokenManagement,
-                credentialAdministration,
-                personalConnection,
-                operator,
-                ...(interactive && operator ? { uiAdminEligible: true } : {}),
             };
         }
         lastResponse = result.response;
@@ -245,15 +239,57 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             }), request, baseUrl, auth, explicit ? candidates[0] : undefined),
     };
 }
+/** The machine-only challenge: Bearer, with no authorization server to discover. */
+function agentChallenge() {
+    return {
+        ok: false,
+        response: privateJson({ error: "unauthorized" }, { status: 401, headers: { "WWW-Authenticate": "Bearer" } }),
+    };
+}
+/**
+ * Admission at an agent endpoint, `/agent/<pool>` (#837). Only the built-in
+ * `cta_` adapter is consulted: Clerk and Access never run, cookies and Clerk
+ * handshake parameters are stripped, and the runtime context, which carries
+ * Access's `ctx.access` even on a bypassed path, is never passed. Anything but
+ * an admitted declared agent gets the machine-only challenge.
+ */
+export async function authorizeAgent(request, baseUrl, auth) {
+    const provider = auth.find(assertsAgents);
+    if (!provider || !isMachineCredential(request))
+        return agentChallenge();
+    let result;
+    try {
+        result = await provider.authorize(authorizationRequest(request), baseUrl, undefined);
+    }
+    catch {
+        return agentChallenge();
+    }
+    if (!result.ok) {
+        void result.response.body?.cancel().catch(() => { });
+        return agentChallenge();
+    }
+    const { agent } = result;
+    if (!isAgentName(agent) || result.userId !== undefined || result.principal !== undefined)
+        return agentChallenge();
+    const namespace = activityActorNamespace(provider);
+    const subject = { namespace: namespace ?? `connecta:auth:${provider.kind}`, id: result.subjectId ?? agent };
+    const actor = { kind: provider.kind, id: agent, ...(namespace ? { namespace } : {}) };
+    return {
+        ok: true,
+        actor,
+        identity: { actor, subject, agent, interactive: false },
+        subjectKey: await identityStorageKey(subject),
+    };
+}
 /** Human routes reject machine credentials before any verification or storage I/O. */
-export async function authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig) {
+export async function authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext) {
     if (!auth.some((provider) => provider.interactiveOperator)) {
         return {
             ok: false,
             response: privateJson({ error: `${purpose} requires interactive user authentication` }, { status: 403 }),
         };
     }
-    return authorize(request, baseUrl, auth, runtimeContext, identityConfig, true, true);
+    return authorize(request, baseUrl, auth, runtimeContext, true, true);
 }
 export function isSameOrigin(request, baseUrl) {
     const origin = request.headers.get("origin");
@@ -281,24 +317,79 @@ export function withSecurityHeaders(response, requestUrl, _path) {
         headers,
     });
 }
-/** Unknown configured ids refuse the complete view, including management rights. */
-export function validateAuthPermissions(authz, registry) {
-    for (const value of [authz.connectorIds, authz.credentialAdministration, authz.personalConnection]) {
-        if (value === "all" || value === "none")
+/**
+ * Plain `/mcp` and every operator route admit a maintainer (#837). An open
+ * deployment has no inbound auth and so no maintainers: its one anonymous
+ * caller keeps the whole default endpoint, as the startup warning says.
+ */
+export function admitsMaintainer(opts, authz) {
+    return opts.config.auth.length === 0 || isMaintainer(opts.maintainers, authz.identity);
+}
+/**
+ * The declared pool `/mcp/<name>` serves to this person, or undefined for the
+ * same 404. An agent is never admitted here, even when listed (#837).
+ */
+export function memberPool(opts, name, identity) {
+    if (identity.agent !== undefined)
+        return undefined;
+    const pool = opts.pools.get(name);
+    return pool?.members.some((member) => isMember(member, identity)) ? pool : undefined;
+}
+/** The declared pool `/agent/<name>` serves to this agent, or undefined for the same 404. */
+export function agentPool(opts, name, identity) {
+    if (identity.agent === undefined)
+        return undefined;
+    const pool = opts.pools.get(name);
+    return pool?.members.some((member) => member.kind === "agent" && isMember(member, identity)) ? pool : undefined;
+}
+/**
+ * The connectors of every pool this identity is a member of (#837): what a
+ * pool member may ever manage, and only their personal ones among these.
+ */
+export function memberConnectors(opts, identity) {
+    const ids = new Set();
+    for (const name of opts.pools.keys()) {
+        const pool = memberPool(opts, name, identity);
+        if (!pool)
             continue;
-        if (!Array.isArray(value) || value.some((id) => !registry.getConnector(id))) {
-            throw new Error("invalid identity permission connector ids");
-        }
+        if (pool.access.connectorIds === "all")
+            return "all";
+        for (const id of pool.access.connectorIds)
+            ids.add(id);
     }
+    return ids;
 }
-export function mayManageConnector(authz, connector) {
-    if (!authz.identity.interactive)
+/**
+ * Whether this identity may start, finish, or remove a connector's auth
+ * (#837). Only an interactive person ever may; an agent or any other machine
+ * credential manages nothing. Shared auth is deployment-wide, so it takes a
+ * maintainer. A personal connector takes a stable principal that is a
+ * maintainer, whose plain `/mcp` includes it, or a member of a pool that
+ * contains it; either way it is always the caller's own partition, which
+ * callers bind by principal. Every path that issues a link, starts,
+ * completes, or disconnects auth, or writes a credential, asks this.
+ */
+export function mayManageConnector(opts, authz, connector) {
+    const identity = authz.identity;
+    if (!identity.interactive || identity.agent !== undefined || !identity.principal)
         return false;
-    if (authz.connectorIds !== "all" && !authz.connectorIds.includes(connector.id)) {
+    if (isMaintainer(opts.maintainers, identity))
+        return true;
+    if (connector.authScope !== "personal")
         return false;
-    }
-    const permission = connector.authScope === "personal" ? authz.personalConnection : authz.credentialAdministration;
-    return permission === "all" || (permission !== "none" && permission.includes(connector.id));
+    const pools = memberConnectors(opts, identity);
+    return pools === "all" || pools.has(connector.id);
+}
+/** Agent token list, issue, rotate, and revoke: an interactive maintainer only (#837). */
+export function managesAgentTokens(opts, authz) {
+    return (authz.identity.interactive && authz.identity.agent === undefined && isMaintainer(opts.maintainers, authz.identity));
+}
+/**
+ * Activity reads: a maintainer principal, interactive or not (#837). Members
+ * and agents read none, and an open deployment has no maintainer.
+ */
+export function readsActivity(opts, authz) {
+    return isMaintainer(opts.maintainers, authz.identity);
 }
 /** Preserve refreshed browser cookies on the redirect or completion page. */
 export function withSessionCookies(response, cookies) {