@zackbart/connecta 0.21.2 → 0.22.0

package/dist/routes/shared.d.ts

@@ -5,11 +5,13 @@ import type { CredentialVault } from "../credentials.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
-import type { ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
+import type { AuthenticatedIdentity, ConnectaBranding, Executor, IdentityReference, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
+import type { ConnectaIdentityConfig } from "../index.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
     registry: Registry;
     auth: InboundAuth[];
+    identity?: ConnectaIdentityConfig | undefined;
     publicUrl?: string | undefined;
     serverInfo: Implementation;
     logger: Logger;
@@ -64,21 +66,35 @@ export declare function privateJson(body: unknown, init?: ResponseInit): Respons
  */
 export declare function loggableValue(requested: string): string;
 export declare function activityActorNamespace(provider: InboundAuth): string | undefined;
-export declare function authorize(request: Request, baseUrl: string, auth: InboundAuth[], runtimeContext?: RuntimeExecutionContext): Promise<{
+export declare function authorize(request: Request, baseUrl: string, auth: InboundAuth[], runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig, partitionIdentity?: boolean): Promise<{
     ok: true;
     actor: ActivityActor;
-    /** True only when the admitting provider can also authorize UI mutation. */
+    identity: AuthenticatedIdentity;
+    subjectKey?: string;
+    principalKey?: string;
+    connectorIds: "all" | readonly string[];
+    operator: boolean;
+    /** Backward-compatible name used by operator views. */
     uiAdminEligible?: boolean;
 } | {
     ok: false;
     response: Response;
 }>;
-export declare function authorizeUiAdmin(request: Request, baseUrl: string, auth: InboundAuth[], purpose?: string, runtimeContext?: RuntimeExecutionContext): Promise<{
+export declare function authorizeUiAdmin(request: Request, baseUrl: string, auth: InboundAuth[], purpose?: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<{
     ok: true;
     userId: string;
+    principal?: IdentityReference;
+    principalKey?: string;
+    connectorIds: "all" | readonly string[];
 } | {
     ok: false;
     response: Response;
 }>;
+export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<Extract<Awaited<ReturnType<typeof authorize>>, {
+    ok: true;
+}> | {
+    ok: false;
+    response: Response;
+}>;
 export declare function isSameOrigin(request: Request, baseUrl: string): boolean;
 export declare function withSecurityHeaders(response: Response, requestUrl: URL, path: string): Response;

package/dist/routes/shared.js

@@ -1,3 +1,4 @@
+import { identityStorageKey, validIdentityReference } from "../identity.js";
 import { operatorPageForPath } from "../ui.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
@@ -29,9 +30,21 @@ export function activityActorNamespace(provider) {
         ? provider.activityActorNamespace
         : undefined;
 }
-export async function authorize(request, baseUrl, auth, runtimeContext) {
+export async function authorize(request, baseUrl, auth, runtimeContext, identityConfig, partitionIdentity = true) {
     if (auth.length === 0) {
-        return { ok: true, actor: { kind: "anonymous" } };
+        const actor = { kind: "anonymous" };
+        const identity = { actor, interactive: false };
+        let connectorIds = "all";
+        try {
+            connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+        }
+        catch {
+            return {
+                ok: false,
+                response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
+            };
+        }
+        return { ok: true, actor, identity, connectorIds, operator: false };
     }
     let lastResponse = null;
     for (const provider of auth) {
@@ -39,18 +52,56 @@ export async function authorize(request, baseUrl, auth, runtimeContext) {
         if (result.ok) {
             const subjectId = result.subjectId ?? result.userId;
             const actorNamespace = activityActorNamespace(provider);
+            const subject = subjectId && actorNamespace
+                ? { namespace: actorNamespace, id: subjectId }
+                : undefined;
+            const derivedPrincipal = result.userId && actorNamespace
+                ? { namespace: actorNamespace, id: result.userId }
+                : undefined;
+            const principal = validIdentityReference(result.principal)
+                ? result.principal
+                : derivedPrincipal;
+            const interactive = Boolean(result.userId && provider.interactiveOperator);
+            const actor = {
+                kind: provider.kind,
+                ...(subjectId ? { id: subjectId } : {}),
+                ...(subject ? { namespace: subject.namespace } : {}),
+            };
+            const identity = {
+                actor,
+                ...(subject ? { subject } : {}),
+                ...(principal ? { principal } : {}),
+                interactive,
+            };
+            let operator = interactive;
+            let connectorIds = "all";
+            try {
+                if (identityConfig?.operatorAccess) {
+                    operator = interactive && principal
+                        ? await identityConfig.operatorAccess(principal)
+                        : false;
+                }
+                connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+            }
+            catch {
+                return {
+                    ok: false,
+                    response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
+                };
+            }
             return {
                 ok: true,
-                actor: {
-                    kind: provider.kind,
-                    ...(subjectId ? { id: subjectId } : {}),
-                    ...(subjectId && actorNamespace
-                        ? { namespace: actorNamespace }
-                        : {}),
-                },
-                ...(result.userId && provider.interactiveOperator
-                    ? { uiAdminEligible: true }
+                actor,
+                identity,
+                ...(subject && partitionIdentity
+                    ? { subjectKey: await identityStorageKey(subject) }
+                    : {}),
+                ...(principal && partitionIdentity
+                    ? { principalKey: await identityStorageKey(principal) }
                     : {}),
+                connectorIds,
+                operator,
+                ...(operator ? { uiAdminEligible: true } : {}),
             };
         }
         lastResponse = result.response;
@@ -67,7 +118,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext) {
             }),
     };
 }
-export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management", runtimeContext) {
+export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management", runtimeContext, identityConfig) {
     // Operator mutation is intentionally narrower than /mcp and /ui/data: only
     // an interactive provider may admit it. A static bearer token is useful
     // for headless tool calls but must not become a deployment-admin key.
@@ -76,30 +127,47 @@ export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "creden
     // Stopping at the first would make admission depend on config order: a failed gate or
     // missing user may simply mean a later provider is the one meant to admit.
     // The last refusal is returned if none do.
+    const authz = await authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig);
+    if (!authz.ok)
+        return authz;
+    if (!authz.operator || !authz.actor.id) {
+        return {
+            ok: false,
+            response: privateJson({ error: `${purpose} requires operator access` }, { status: 403 }),
+        };
+    }
+    return {
+        ok: true,
+        userId: authz.identity.principal?.id ?? authz.actor.id,
+        ...(authz.identity.principal
+            ? { principal: authz.identity.principal }
+            : {}),
+        ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
+        connectorIds: authz.connectorIds,
+    };
+}
+export async function authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig) {
     const providers = auth.filter((candidate) => candidate.interactiveOperator);
     if (providers.length === 0) {
         return {
             ok: false,
-            response: privateJson({ error: `${purpose} requires interactive operator authentication` }, { status: 403 }),
+            response: privateJson({ error: `${purpose} requires interactive user authentication` }, { status: 403 }),
         };
     }
-    let lastResponse = null;
+    let lastResponse;
     for (const provider of providers) {
-        const result = await provider.authorize(request, baseUrl, runtimeContext);
-        if (!result.ok) {
-            lastResponse = result.response;
+        const authz = await authorize(request, baseUrl, [provider], runtimeContext, identityConfig);
+        if (!authz.ok) {
+            lastResponse = authz.response;
             continue;
         }
-        if (!result.userId) {
-            lastResponse = privateJson({ error: "authenticated user required" }, { status: 403 });
-            continue;
-        }
-        return { ok: true, userId: result.userId };
+        if (authz.identity.interactive)
+            return authz;
+        lastResponse = privateJson({ error: "authenticated user required" }, { status: 403 });
     }
     return {
         ok: false,
-        response: lastResponse ??
-            privateJson({ error: "forbidden" }, { status: 403 }),
+        response: lastResponse ?? privateJson({ error: `${purpose} requires interactive user authentication` }, { status: 403 }),
     };
 }
 export function isSameOrigin(request, baseUrl) {

package/dist/routes/ui.js

@@ -1,6 +1,6 @@
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
 import { buildUiData, CONNECTA_FAVICON_SVG, credentialManagementCapability, operatorPageForPath, renderUiHtml, } from "../ui.js";
-import { authorize, privateJson, } from "./shared.js";
+import { authorize, msg, privateJson, } from "./shared.js";
 /**
  * Headers that make an operator-supplied favicon body inert on this origin.
  * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
@@ -99,17 +99,35 @@ export async function routeUi(context) {
     }
     if (path !== "/ui/data")
         return null;
-    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
+    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
     if (!authz.ok)
         return authz.response;
+    let registry;
+    try {
+        registry = opts.registry.scoped({
+            connectorIds: authz.connectorIds,
+            ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
+            ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
+        });
+    }
+    catch (error) {
+        return privateJson({ error: msg(error) }, { status: 403 });
+    }
     const eligibleOperator = authz.uiAdminEligible === true;
-    const credentialManagement = credentialManagementCapability({
-        eligibleOperator,
-        hasCredentialSlots: opts.registry
-            .listConnectors()
-            .some((connector) => Boolean(connector.credential)),
-        hasCredentialVault: Boolean(opts.credentialVault),
-    });
+    const interactiveManager = authz.identity.interactive;
+    const personalManager = Boolean(interactiveManager && authz.principalKey);
+    const visibleConnectors = registry.listConnectors();
+    const hasManageableCredentialSlot = visibleConnectors.some((connector) => Boolean(connector.credential) &&
+        (connector.authScope !== "personal" || personalManager));
+    const credentialManagement = interactiveManager && hasManageableCredentialSlot
+        ? opts.credentialVault
+            ? "available"
+            : "vault_not_configured"
+        : credentialManagementCapability({
+            eligibleOperator: interactiveManager,
+            hasCredentialSlots: visibleConnectors.some((connector) => Boolean(connector.credential)),
+            hasCredentialVault: Boolean(opts.credentialVault),
+        });
     // As with connector credentials, a Bearer-authenticated observer learns
     // only that an interactive operator is required, not whether this deployment has opted into
     // token issuance. Configuration topology is operator data.
@@ -118,9 +136,10 @@ export async function routeUi(context) {
         : opts.accessTokens
             ? "available"
             : "not_configured";
-    const data = await buildUiData(opts.registry, baseUrl, opts.serverInfo, 
-    // The static headless bearer may read connector health, but only a
-    // Clerk-authenticated operator receives credential metadata.
-    eligibleOperator ? opts.credentialVault : undefined, Boolean(opts.activity?.list), credentialManagement, defer, eligibleOperator, opts.discoveryConcurrency, accessTokenManagement);
+    const data = await buildUiData(registry, baseUrl, opts.serverInfo, 
+    // A static headless bearer may read connector health, but only an
+    // interactive human receives credential metadata for visible connectors.
+    interactiveManager ? opts.credentialVault : undefined, Boolean(opts.activity?.list) &&
+        (!opts.identity?.operatorAccess || eligibleOperator), credentialManagement, defer, interactiveManager, opts.discoveryConcurrency, accessTokenManagement, personalManager ? authz.principalKey : undefined);
     return privateJson(data);
 }

package/dist/types.d.ts

@@ -138,7 +138,7 @@ export interface ConnectorContext {
     /** Public base URL of this deployment (origin), used for OAuth callbacks. */
     baseUrl: string;
     /**
-     * Read-only access to this connector's operator-managed credential. Present
+     * Read-only access to this connector's human-managed credential. Present
      * only when the connector declares `credential` and the deployment configures
      * `credentials.encryptionKey`.
      */
@@ -208,6 +208,12 @@ export interface ConnectorStatus {
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
     id: string;
+    /**
+     * Who owns this connector's downstream authentication. `shared` keeps one
+     * deployment-wide grant. `personal` isolates storage and credentials by the
+     * authenticated human principal. Defaults to `shared`.
+     */
+    authScope?: "shared" | "personal";
     /** Human-readable display name; the stable `id` remains the tool-address prefix. */
     title?: string;
     /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
@@ -240,7 +246,7 @@ export interface Connector {
      * configuration; no runtime registration or shared mutable copy exists.
      */
     usageGuide?: string | ConnectorUsageGuide;
-    /** Optional operator-managed credential slot rendered on /credentials. */
+    /** Optional human-managed credential slot rendered on /credentials. */
     credential?: ConnectorCredentialConfig;
     /** Optional server-side check used by /credentials' Test action. */
     testCredential?(value: string, ctx: ConnectorContext): Promise<CredentialTestResult>;
@@ -420,10 +426,30 @@ export type AuthResult = {
     ok: true;
     userId?: string;
     subjectId?: string;
+    /** Human owner represented by a non-interactive access credential. */
+    principal?: IdentityReference;
 } | {
     ok: false;
     response: Response;
 };
+/** Stable identity inside one configured authentication directory. */
+export interface IdentityReference {
+    namespace: string;
+    id: string;
+}
+/** Identity data passed to config-owned access resolvers. */
+export interface AuthenticatedIdentity {
+    actor: {
+        kind: string;
+        id?: string;
+        namespace?: string;
+    };
+    /** Any stable admitted caller, including service identities and tokens. */
+    subject?: IdentityReference;
+    /** Human owner of personal connector authentication. */
+    principal?: IdentityReference;
+    interactive: boolean;
+}
 /** Public browser-auth configuration exposed to connecta's status UI. */
 export type UiAuthConfig = {
     kind: "cloudflare-access";

package/dist/ui.d.ts

@@ -1,7 +1,7 @@
 import type { CredentialVault } from "./credentials.js";
 import { type DeferredWork } from "./connector-scope.js";
 import { type CredentialManagementCapability, type AccessTokenManagementCapability, type UiData } from "./operator-ui/model.js";
-import type { Registry } from "./registry.js";
+import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type AccessTokenManagementCapability, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 /** Connecta's default monochrome "C" mark. */
@@ -82,10 +82,10 @@ export declare function credentialManagementCapability(input: {
  * isolated: they surface status "error" with an empty tool list rather than
  * failing the whole payload.
  */
-export declare function buildUiData(registry: Registry, baseUrl: string, serverInfo: {
+export declare function buildUiData(registry: RegistryView, baseUrl: string, serverInfo: {
     name: string;
     version: string;
-}, credentialVault?: CredentialVault, activityEnabled?: boolean, credentialManagement?: CredentialManagementCapability, defer?: DeferredWork, oauthManagement?: boolean, discoveryConcurrency?: number, accessTokenManagement?: AccessTokenManagementCapability): Promise<UiData>;
+}, credentialVault?: CredentialVault, activityEnabled?: boolean, credentialManagement?: CredentialManagementCapability, defer?: DeferredWork, oauthManagement?: boolean, discoveryConcurrency?: number, accessTokenManagement?: AccessTokenManagementCapability, personalCredentialOwner?: string): Promise<UiData>;
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.

package/dist/ui.js

@@ -223,7 +223,7 @@ export function credentialManagementCapability(input) {
  */
 export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault
     ? "available"
-    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, accessTokenManagement = "not_configured") {
+    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, accessTokenManagement = "not_configured", personalCredentialOwner) {
     const requestScope = {};
     const connectorSet = registry.listConnectors();
     const concurrency = resolveDiscoveryConcurrency(discoveryConcurrency);
@@ -232,6 +232,9 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         const status = drift
             ? { state: "auth_required", message: drift }
             : await registry.statusFor(c.id, baseUrl, requestScope);
+        if (status.authorizationUrl) {
+            await registry.bindOAuthHandoff(c.id, status.authorizationUrl);
+        }
         let tools = [];
         // `status()` on an unauthenticated remote connector starts OAuth and
         // stores its state + PKCE verifier. Probing listTools immediately
@@ -253,7 +256,10 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             }
         }
         let credential;
-        if (c.credential && credentialVault) {
+        const mayManageAuth = c.authScope === "personal"
+            ? Boolean(personalCredentialOwner)
+            : oauthManagement;
+        if (c.credential && credentialVault && mayManageAuth) {
             // One rule, shared with the test route: only the hook matching the
             // declared credential shape can run, so the button is offered only
             // where a click can succeed (src/credentials.ts).
@@ -289,7 +295,7 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
                     : {}),
             };
             try {
-                const metadata = await credentialVault.metadata(c.id);
+                const metadata = await credentialVault.metadata(c.id, c.authScope === "personal" ? personalCredentialOwner : undefined);
                 const fields = credentialFields(metadata);
                 const shape = storedCredentialShape(c.credential, metadata?.fields ?? null);
                 credential = {
@@ -331,6 +337,7 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         }
         return {
             id: c.id,
+            authScope: c.authScope ?? "shared",
             ...(c.title ? { title: c.title } : {}),
             ...(c.description !== undefined
                 ? { description: c.description }
@@ -350,7 +357,13 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             ...(status.catalogAccess
                 ? { catalogAccess: status.catalogAccess }
                 : {}),
-            ...(c.disconnectAuth && c.startAuth ? { oauth: true } : {}),
+            ...(c.disconnectAuth &&
+                c.startAuth &&
+                (oauthManagement ||
+                    c.authScope === "personal" ||
+                    !personalCredentialOwner)
+                ? { oauth: true }
+                : {}),
             ...(credential ? { credential } : {}),
         };
     });
@@ -367,7 +380,7 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         activityEnabled,
         credentialManagement,
         accessTokenManagement,
-        oauthManagement,
+        oauthManagement: oauthManagement || Boolean(personalCredentialOwner),
     };
 }
 function escapeHtmlAttr(value) {

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.21.2";
+export declare const CONNECTA_VERSION = "0.22.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.21.2";
+export const CONNECTA_VERSION = "0.22.0";

package/documentation/architecture.md

@@ -70,7 +70,7 @@ read top to bottom.
 | 2 | `OPTIONS` | Each auth provider's `handleMetadata` gets a chance (CORS preflight for browser MCP clients); otherwise 204 with MCP CORS. |
 | 3 | `/.well-known/*` | Auth providers' `handleMetadata`, open. 404 when none handles it. |
 | 4 | `/health` | Open JSON: status, connector count, `serverInfo`, the configured executor's sanitized name when it has one, catalog-drift counts, admission snapshots, reserved route names, and `deployment` when `deploymentInfo` is set. Payload-free by construction, and it never joins the MCP queue. |
-| 5 | `/oauth/callback/<connectorId>` | Downstream-OAuth completion, open, `verifyState` before `finishAuth`. |
+| 5 | `/oauth/callback/<connectorId>` | Downstream-OAuth completion, open, `verifyState` before `finishAuth`. Personal flows first resolve the short-lived state hash to the principal partition. |
 | 6 | `/favicon.*`, `/ui` → `/`, the operator shells, `/ui/data` | The operator surface ([operator UI](./operator-ui.md)). The shells are open and data-free; `/ui/data` behind them is gated. Built-ins are matched before connector routes, so a connector cannot shadow a page. |
 | 7 | `/ui/activity` | Gated, plus the optional `activity.readGate`. `GET` only; 404 with no `activity.store.list`. |
 | 8 | `/mcp` | **Admission before auth**, then the auth gate, then a fresh MCP server. |
@@ -93,11 +93,15 @@ any one file and a reordering reads like a harmless refactor.
    before interactive providers. First `ok` admits; if all fail, the last provider's challenge
    response is returned. No providers configured means open — development
    only, and it warns at construction.
-3. **Refuse `?toolkit=`.** Toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
+3. **Derive the registry view.** Auth supplies a namespaced subject and, for a
+   human, a principal. `identity.connectorAccess` selects declared connector
+   ids. Personal connectors use the principal partition; result paging uses
+   the subject partition. No caller parameter selects either.
+4. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
    but the URLs naming them were handed out, so the parameter is a 404 rather
    than silently serving the full registry. Retiring a scoping boundary into
    fail-open is the one outcome worse than the 404.
-4. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
+5. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
    against the registry, the Apps shell resource registered (and
    `resources/list` deliberately answering with nothing), and the response
    handed back.
@@ -109,7 +113,7 @@ owns or hands out, and a change usually belongs in exactly one of them:
 
 | Module | Owns |
 | --- | --- |
-| `src/registry.ts` | The connector set, address resolution, catalog TTL/persistence/completeness, shared refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
+| `src/registry.ts` | The connector set, identity-scoped views, personal storage partitions, address resolution, catalog TTL/persistence/completeness, refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
 | `src/catalog-service.ts` | Request-local tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
 | `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
@@ -184,10 +188,12 @@ src/
 
 ## Sharp edges
 
-- **The registry is shared; the request is not.** Anything you cache on the
-  registry is visible to every later request in that isolate. Anything you
-  cache per request dies with it. Putting a downstream client on the wrong side
-  of that line is the highest-severity mistake available here.
+- **The root registry is shared; identity views are partitioned.** Shared
+  connector caches are visible to later requests in the isolate. Personal
+  connectors use a bounded principal registry, and transient results use the
+  authenticated subject. Anything cached per request still dies with it.
+  Putting a downstream client or credential on the wrong side of those lines
+  is the highest-severity mistake available here.
 - **Route order is behavior.** Moving a built-in below the connector dispatch
   hands a connector the ability to shadow it. Moving a mutation route below the
   wildcard `OPTIONS` opts it into CORS preflight.

package/documentation/auth.md

@@ -6,6 +6,63 @@ Access identities on Workers, or a mixture. Static bearers are checked first;
 the remaining providers keep configuration order. The first successful
 identity owns the activity actor for that request.
 
+## Principals, visibility, and operators
+
+Connecta distinguishes three identities. The actor is the exact caller written
+to activity. The subject is any stable authenticated caller and owns transient
+results such as `get_result` pages. The principal is the human owner of personal
+connector auth. An interactive Clerk or Access user supplies all three. A
+Cloudflare service identity has an actor and subject but no principal. A
+connecta access token has its own actor and subject and inherits the principal
+that created it, so agents using that token reach the creator's personal
+connections without becoming operators.
+
+`identity.connectorAccess` derives the connector ids a caller may discover and
+invoke. The resolver receives authenticated identity data, never request input,
+and returns `"all"` or a list of ids declared in `connectors`. An unknown id or
+a thrown resolver fails the request closed.
+
+`identity.connectorAccess` is also the credential-management boundary. A
+signed-in human may save, test, disconnect, and authorize every visible
+connector: personal auth changes only that principal's partition, while shared
+auth changes the deployment-wide grant for everyone who can see the connector.
+Use `authScope: "personal"` when one member must not rotate another member's
+connection.
+
+`identity.operatorAccess` separately reserves deployment-wide administration:
+access-token creation and global activity history. Omit the resolver to
+preserve the prior rule that every interactive human is an operator. When it is
+configured, activity history is operator-only because its global event stream
+contains other principals' connector names and actors.
+
+```ts
+createConnecta({
+  auth: cloudflareAccessAuth(),
+  identity: {
+    connectorAccess: ({ principal }) =>
+      principal?.id === "user_a"
+        ? ["shared_docs", "personal_linear"]
+        : ["shared_docs"],
+    operatorAccess: ({ id }) => id === "user_a",
+  },
+  connectors: [
+    remoteMcp("shared_docs", { url: "https://example.com/mcp" }),
+    remoteMcp("personal_linear", {
+      url: "https://mcp.linear.app/mcp",
+      authScope: "personal",
+      auth: { type: "oauth" },
+    }),
+  ],
+  executor,
+});
+```
+
+Identity namespaces matter. Built-in Clerk and Access providers supply one.
+A custom interactive provider must set `activityActorNamespace` before its
+users can own personal auth. It may still use the legacy operator behavior
+without one, but connecta will not merge unnamespaced users into personal
+storage.
+
 ## Cloudflare Access on Workers
 
 [`cloudflareAccessAuth()`](https://developers.cloudflare.com/workers/configuration/cloudflare-access/)
@@ -35,7 +92,8 @@ also means it is deliberately not a Node or `cloudflared` origin adapter, and
 it does not survive a Service Binding hop: those shapes need their own explicit
 trust boundary.
 
-A human identity gets MCP and operator access. A Cloudflare service-token
+A human identity gets MCP and personal-connection access. It gets operator
+access unless `identity.operatorAccess` says otherwise. A Cloudflare service-token
 identity gets MCP access and a stable activity subject, but no `userId`, so it
 cannot write credentials, run downstream OAuth mutations, or issue connecta
 tokens. Access policy decides who reaches the Worker; connecta does not mirror
@@ -48,7 +106,27 @@ the Worker. Enable [**Managed OAuth**](https://developers.cloudflare.com/cloudfl
 on that Worker-level application for interactive MCP clients.
 Cloudflare then owns the unauthenticated challenge and `/.well-known/`
 metadata, issues opaque RFC 8707 tokens, and resolves them into the same trusted
-Worker identity. Do not add a bypass for the discovery routes. A fully
+Worker identity. Managed OAuth allows no hosted client callback by default, so
+enable Dynamic Client Registration and add all three values to **Allowed
+redirect URIs**:
+
+```text
+https://claude.ai/api/mcp/auth_callback
+https://chatgpt.com/connector_platform_oauth_redirect
+https://chatgpt.com/connector/oauth/*
+```
+
+Cloudflare exposes that list as
+`oauth_configuration.dynamic_client_registration.allowed_uris`. It belongs to
+the Access application's Managed OAuth settings, not the Access policy that
+selects admitted identities. Claude uses the fixed first value. ChatGPT may use
+its stable callback or a callback-id path covered by the third value. If a
+client registers a different redirect, add that exact URI or the narrowest path
+wildcard that covers it; do not allow the client's whole origin. Without these
+entries discovery succeeds and client registration fails later, which makes a
+missing allowlist look like a broken MCP server.
+
+Do not add a bypass for the discovery routes. A fully
 automated client instead uses a [Cloudflare Access service token](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/)
 through the
 `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers.
@@ -102,7 +180,9 @@ secure.
 Each token has an immutable ID. Activity records store that ID and resolve its
 current friendly name only while an authorized operator reads activity.
 Revoked records remain as metadata tombstones so historical calls keep their
-friendly attribution.
+friendly attribution. New tokens also retain the creating principal. Their MCP
+requests use that principal's connector visibility and personal auth while the
+token itself remains the activity actor and result owner.
 
 Access tokens authenticate MCP clients; they are never operator credentials.
 Creation, rename, and revocation require the same eligible human identity and
@@ -113,20 +193,20 @@ Issuance and revocation inherit the consistency guarantees of the configured
 storage adapter. Use strongly consistent storage when either change must take
 effect globally without a convergence window.
 
-Operator credential mutation is a separate, narrower boundary. The
+Human credential mutation is a separate, narrower boundary. The
 `/credentials` shell contains no secret data before authentication, and the
-mutation API requires same-origin requests from an admitted operator. An MCP
-bearer is never treated as an operator credential, even when it can call every
-connector.
+mutation API requires same-origin requests from an admitted interactive human.
+That human may mutate only visible connector slots. An MCP bearer is never
+treated as a browser credential, even when it can call every connector.
 
 This split is visible in recovery:
 
 - a bearer-authenticated agent may receive `recovery: "operator_config"` and
   pass its `operatorUrl` to a human;
-- an interactive operator opens that URL, signs in, and updates the
+- an interactive human with connector access opens that URL, signs in, and updates the
   credential; and
 - a bearer-only deployment still returns the handoff honestly, but mutation
-  remains unavailable until interactive operator auth is configured.
+  remains unavailable until interactive user auth is configured.
 
 See [meta-tools](./meta-tools.md#authorization-recovery) for the stable recovery
 envelope and [storage and credentials](./storage-and-credentials.md) for vault