@zackbart/connecta 0.21.2 → 0.22.0

package/dist/providers/revenuecat.d.ts

@@ -5,6 +5,8 @@ export declare const REVENUECAT_MCP_ENDPOINT = "https://mcp.revenuecat.ai/mcp";
 export interface RevenueCatOptions {
     /** Display name; scope defaults are in `documentation/revenuecat.md`. */
     title?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
     /**
      * Which project this connector is for and what decisions it answers. With
      * headers auth this is the only place the project a key reaches is named,

package/dist/providers/revenuecat.js

@@ -207,6 +207,7 @@ export function revenuecat(id, options) {
     const scoped = auth.type !== "oauth";
     const connector = remoteMcp(id, {
         url: REVENUECAT_MCP_ENDPOINT,
+        ...(options.authScope ? { authScope: options.authScope } : {}),
         // The scope shape rides the title because browse-time discovery renders
         // the title and the guide summary and nothing else, and reaching one
         // project versus every project the account has is the fact an agent must

package/dist/providers/stripe.d.ts

@@ -7,6 +7,8 @@ export declare const STRIPE_MCP_ENDPOINT = "https://mcp.stripe.com/";
 interface StripeCommonOptions {
     /** Human-readable display name; defaults to "Stripe" for OAuth. */
     title?: string;
+    /** Downstream auth ownership. Defaults to one shared deployment grant. */
+    authScope?: "shared" | "personal";
     /** Which business purpose and Stripe context this connector is for. */
     purpose: string;
     /** Connector-specific conventions appended to the maintained provider guide. */

package/dist/providers/stripe.js

@@ -192,6 +192,7 @@ export function stripe(id, options) {
     const copy = mode === undefined ? undefined : MODE_COPY[mode];
     const connector = remoteMcp(id, {
         url: STRIPE_MCP_ENDPOINT,
+        ...(options.authScope ? { authScope: options.authScope } : {}),
         title: options.title ?? copy?.title ?? "Stripe",
         description: mode === undefined
             ? `Stripe payments (live and sandbox accounts) — ${purpose}`

package/dist/registry.d.ts

@@ -47,6 +47,10 @@ export interface RegistryOptions {
     storage: KVStorage;
     logger: Logger;
     credentialVault?: CredentialVault | undefined;
+    /** Internal owner partition used by a personal registry. */
+    credentialOwner?: string | undefined;
+    /** Internal child registries skip deployment-wide construction warnings. */
+    constructionChecks?: boolean | undefined;
     toolCacheTtlSeconds?: number | undefined;
     persistToolCatalog?: boolean | undefined;
     toolCatalogStaleSeconds?: number | undefined;
@@ -105,6 +109,13 @@ export interface RegistryView {
     observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
     statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ConnectorStatus>;
     invalidateStored(id: string): Promise<void>;
+    /** Bind returned OAuth state to this view's personal storage partition. */
+    bindOAuthHandoff(id: string, authorizationUrl: string): Promise<void>;
+}
+export interface RegistryScope {
+    connectorIds: "all" | readonly string[];
+    subjectKey?: string;
+    principalKey?: string;
 }
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
@@ -136,7 +147,20 @@ export declare class Registry implements RegistryView {
     private readonly persistToolCatalog;
     /** Result-size guard cap threaded to the meta-tools. */
     readonly maxResultBytes: number;
+    private readonly configuredConnectors;
+    private readonly personalRegistries;
     constructor(connectors: Connector[], opts: RegistryOptions);
+    personalRegistry(principalKey: string): Registry;
+    /** Build the only connector view an authenticated request receives. */
+    scoped(scope: RegistryScope): RegistryView;
+    scopedStorage(subjectKey: string): KVStorage;
+    private oauthHandoffKey;
+    storeOAuthHandoff(connectorId: string, state: string, principalKey: string): Promise<void>;
+    oauthCallbackView(connectorId: string, state: string | null): Promise<{
+        registry: RegistryView;
+        principalKey?: string;
+    } | null>;
+    clearOAuthHandoff(connectorId: string, state: string | null): Promise<void>;
     /**
      * Warn once per unusable result cap, at construction time — the same
      * "runs fine but is surely unintended" channel as the insecure-config
@@ -193,6 +217,7 @@ export declare class Registry implements RegistryView {
      * separate from any connector's `conn:<id>:` namespace. Backs get_result.
      */
     resultsStorage(): KVStorage;
+    bindOAuthHandoff(): Promise<void>;
     observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
     observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
     /** Resolve "<connectorId>.<toolName>" → connector + tool name. */

package/dist/registry.js

@@ -73,8 +73,21 @@ function namespaced(storage, prefix) {
         get: (k) => storage.get(prefix + k),
         set: (k, v, o) => storage.set(prefix + k, v, o),
         delete: (k) => storage.delete(prefix + k),
+        ...(storage.list
+            ? {
+                list: async (keyPrefix) => (await storage.list(prefix + keyPrefix)).map((key) => key.slice(prefix.length)),
+            }
+            : {}),
     };
 }
+const MAX_PERSONAL_REGISTRIES = 1_024;
+const OAUTH_HANDOFF_TTL_SECONDS = 15 * 60;
+async function sha256Hex(value) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+    return [...bytes]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
 /**
  * Holds the connector set, resolves addresses, and caches per-connector tool
  * lists in memory with a TTL. Connector failures are isolated: a broken
@@ -105,8 +118,11 @@ export class Registry {
     persistToolCatalog;
     /** Result-size guard cap threaded to the meta-tools. */
     maxResultBytes;
+    configuredConnectors;
+    personalRegistries = new Map();
     constructor(connectors, opts) {
         this.opts = opts;
+        this.configuredConnectors = [...connectors];
         this.observedOutputSchemas = new ObservedOutputSchemas();
         this.ttlMs =
             (opts.toolCacheTtlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
@@ -121,6 +137,11 @@ export class Registry {
             if (this.connectors.has(c.id)) {
                 throw new Error(`Duplicate connector id "${c.id}"`);
             }
+            if (c.authScope !== undefined &&
+                c.authScope !== "shared" &&
+                c.authScope !== "personal") {
+                throw new Error(`Invalid authScope on connector "${c.id}": expected "shared" or "personal"`);
+            }
             const configuredGuideSummary = typeof c.usageGuide === "object"
                 ? normalizeGuideSummary(c.usageGuide.summary ?? "")
                 : undefined;
@@ -136,8 +157,82 @@ export class Registry {
                 this.callAdmission.set(c.id, new ConnectorCallAdmissionController(c.id, c.callAdmission));
             }
         }
-        this.checkConventions(opts.logger);
-        this.checkResultCaps(opts.logger, opts.maxResultBytes);
+        if (opts.constructionChecks !== false) {
+            this.checkConventions(opts.logger);
+            this.checkResultCaps(opts.logger, opts.maxResultBytes);
+        }
+    }
+    personalRegistry(principalKey) {
+        const existing = this.personalRegistries.get(principalKey);
+        if (existing) {
+            this.personalRegistries.delete(principalKey);
+            this.personalRegistries.set(principalKey, existing);
+            return existing;
+        }
+        const registry = new Registry(this.configuredConnectors.filter((connector) => connector.authScope === "personal"), {
+            ...this.opts,
+            storage: namespaced(this.opts.storage, `principal:${principalKey}:`),
+            credentialOwner: principalKey,
+            constructionChecks: false,
+        });
+        this.personalRegistries.set(principalKey, registry);
+        const oldest = this.personalRegistries.keys().next().value;
+        if (this.personalRegistries.size > MAX_PERSONAL_REGISTRIES &&
+            typeof oldest === "string") {
+            this.personalRegistries.delete(oldest);
+        }
+        return registry;
+    }
+    /** Build the only connector view an authenticated request receives. */
+    scoped(scope) {
+        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}"`);
+            }
+        }
+        return new ScopedRegistryView(this, requested, scope);
+    }
+    scopedStorage(subjectKey) {
+        return namespaced(this.opts.storage, `subject:${subjectKey}:`);
+    }
+    oauthHandoffKey(connectorId, stateHash) {
+        return `oauth-handoff:v1:${connectorId}:${stateHash}`;
+    }
+    async storeOAuthHandoff(connectorId, state, principalKey) {
+        const key = this.oauthHandoffKey(connectorId, await sha256Hex(state));
+        const existing = await this.opts.storage.get(key);
+        if (existing && existing !== principalKey) {
+            throw new Error(`Connector "${connectorId}" reused one OAuth state across principals`);
+        }
+        await this.opts.storage.set(key, principalKey, { ttlSeconds: OAUTH_HANDOFF_TTL_SECONDS });
+    }
+    async oauthCallbackView(connectorId, state) {
+        const connector = this.connectors.get(connectorId);
+        if (!connector)
+            return null;
+        if (connector.authScope !== "personal")
+            return { registry: this };
+        if (!state)
+            return null;
+        const principalKey = await this.opts.storage.get(this.oauthHandoffKey(connectorId, await sha256Hex(state)));
+        if (!principalKey)
+            return null;
+        return {
+            registry: this.scoped({
+                connectorIds: [connectorId],
+                subjectKey: principalKey,
+                principalKey,
+            }),
+            principalKey,
+        };
+    }
+    async clearOAuthHandoff(connectorId, state) {
+        if (!state)
+            return;
+        await this.opts.storage.delete(this.oauthHandoffKey(connectorId, await sha256Hex(state)));
     }
     /**
      * Warn once per unusable result cap, at construction time — the same
@@ -202,7 +297,7 @@ export class Registry {
         if (this.opts.credentialVault && credentialConfig) {
             const vault = this.opts.credentialVault;
             const readValues = async () => {
-                const values = await vault.getAll(id);
+                const values = await vault.getAll(id, this.opts.credentialOwner);
                 const shape = storedCredentialShape(credentialConfig, values);
                 if (shape.state === "mismatch") {
                     throw new ConnectorCallError("auth_required", shape.message);
@@ -310,6 +405,9 @@ export class Registry {
     resultsStorage() {
         return namespaced(this.opts.storage, "results:");
     }
+    async bindOAuthHandoff() {
+        // Shared OAuth already resolves in deployment-wide connector storage.
+    }
     observedOutputSchema(connectorId, definition) {
         return this.observedOutputSchemas.get(connectorId, definition);
     }
@@ -858,7 +956,7 @@ export class Registry {
         if (!credential || !vault)
             return undefined;
         try {
-            const values = await vault.getAll(id);
+            const values = await vault.getAll(id, this.opts.credentialOwner);
             const shape = storedCredentialShape(credential, values);
             return shape.state === "mismatch" ? shape.message : undefined;
         }
@@ -943,3 +1041,101 @@ export class Registry {
             await this.deleteStoredCatalog(id);
     }
 }
+class ScopedRegistryView {
+    root;
+    allowed;
+    scope;
+    maxResultBytes;
+    personal;
+    constructor(root, allowed, scope) {
+        this.root = root;
+        this.allowed = allowed;
+        this.scope = scope;
+        this.maxResultBytes = root.maxResultBytes;
+        this.personal = scope.principalKey
+            ? root.personalRegistry(scope.principalKey)
+            : undefined;
+    }
+    registryFor(id) {
+        if (!this.allowed.has(id))
+            return undefined;
+        const connector = this.root.getConnector(id);
+        if (!connector)
+            return undefined;
+        return connector.authScope === "personal" ? this.personal : this.root;
+    }
+    listConnectors() {
+        return this.root.listConnectors().filter((connector) => this.registryFor(connector.id) !== undefined);
+    }
+    getConnector(id) {
+        return this.registryFor(id)?.getConnector(id);
+    }
+    resolveAddress(address) {
+        const parsed = splitAddress(address);
+        if (!parsed)
+            return null;
+        const connector = this.getConnector(parsed.connectorId);
+        return connector ? { connector, toolName: parsed.toolName } : null;
+    }
+    getTools(...args) {
+        const registry = this.registryFor(args[0]);
+        if (!registry) {
+            return Promise.reject(new Error(`Unknown connector "${args[0]}"`));
+        }
+        return registry.getTools(...args);
+    }
+    contextFor(...args) {
+        const registry = this.registryFor(args[0]);
+        if (!registry)
+            throw new Error(`Unknown connector "${args[0]}"`);
+        return registry.contextFor(...args);
+    }
+    admitCall(...args) {
+        if (!this.registryFor(args[0])) {
+            return Promise.reject(new Error(`Unknown connector "${args[0]}"`));
+        }
+        return this.root.admitCall(...args);
+    }
+    resultsStorage() {
+        return this.scope.subjectKey
+            ? this.root.scopedStorage(this.scope.subjectKey)
+            : this.root.resultsStorage();
+    }
+    credentialDriftFor(id) {
+        const registry = this.registryFor(id);
+        return registry
+            ? registry.credentialDriftFor(id)
+            : Promise.resolve(undefined);
+    }
+    observedOutputSchema(connectorId, definition) {
+        return this.registryFor(connectorId)?.observedOutputSchema(connectorId, definition);
+    }
+    observeOutputShape(connectorId, definition, value) {
+        this.registryFor(connectorId)?.observeOutputShape(connectorId, definition, value);
+    }
+    statusFor(...args) {
+        const registry = this.registryFor(args[0]);
+        return registry
+            ? registry.statusFor(...args)
+            : Promise.resolve({ state: "error", message: "Unknown connector" });
+    }
+    invalidateStored(id) {
+        const registry = this.registryFor(id);
+        return registry ? registry.invalidateStored(id) : Promise.resolve();
+    }
+    async bindOAuthHandoff(id, authorizationUrl) {
+        const connector = this.getConnector(id);
+        if (connector?.authScope !== "personal" || !this.scope.principalKey)
+            return;
+        let state = null;
+        try {
+            state = new URL(authorizationUrl).searchParams.get("state");
+        }
+        catch {
+            return;
+        }
+        if (state) {
+            await this.root.storeOAuthHandoff(id, state, this.scope.principalKey);
+        }
+    }
+}

package/dist/routes/access-tokens.js

@@ -46,7 +46,7 @@ export async function routeAccessTokens(context) {
     if (mutating && !isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "access token management", context.runtimeContext);
+    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "access token management", context.runtimeContext, opts.identity);
     if (!admin.ok)
         return admin.response;
     const id = match[1];
@@ -58,7 +58,7 @@ export async function routeAccessTokens(context) {
             const input = await readName(request);
             if (!input.ok)
                 return input.response;
-            return privateJson(await opts.accessTokens.create(input.name, admin.userId), { status: 201 });
+            return privateJson(await opts.accessTokens.create(input.name, admin.principal ?? admin.userId), { status: 201 });
         }
         if (id && request.method === "PUT") {
             const input = await readName(request);

package/dist/routes/activity.js

@@ -134,9 +134,12 @@ export async function routeActivity(context) {
     if (request.method !== "GET") {
         return privateJson({ error: "method not allowed" }, { status: 405 });
     }
-    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
+    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity, false);
     if (!authz.ok)
         return authz.response;
+    if (opts.identity?.operatorAccess && !authz.operator) {
+        return privateJson({ error: "operator access required" }, { status: 403 });
+    }
     if (opts.activityReadGate &&
         !(await opts.activityReadGate(authz.actor))) {
         return privateJson({ error: "forbidden" }, { status: 403 });

package/dist/routes/credentials.js

@@ -1,5 +1,5 @@
 import { credentialTestRule, describeCredentialTestMismatch, storedCredentialShape, } from "../credentials.js";
-import { authorizeUiAdmin, isSameOrigin, msg, privateJson, } from "./shared.js";
+import { authorizeUiIdentity, isSameOrigin, msg, privateJson, } from "./shared.js";
 async function readCredentialInput(request, config) {
     if (!request.headers
         .get("content-type")
@@ -73,13 +73,32 @@ async function handleCredentialRequest(context, connectorId, action) {
     if (!isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "credential management", context.runtimeContext);
-    if (!admin.ok)
-        return admin.response;
-    const connector = opts.registry.getConnector(connectorId);
+    const authz = await authorizeUiIdentity(request, baseUrl, opts.auth, "credential management", context.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 connector = registry.getConnector(connectorId);
     if (!connector?.credential) {
         return privateJson({ error: "unknown credential slot" }, { status: 404 });
     }
+    const personal = connector.authScope === "personal";
+    if (personal && !authz.principalKey) {
+        return privateJson({ error: "forbidden" }, { status: 403 });
+    }
+    const owner = personal ? authz.principalKey : undefined;
+    const updatedBy = authz.identity.principal
+        ? `${authz.identity.principal.namespace}:${authz.identity.principal.id}`
+        : authz.actor.id ?? authz.actor.kind;
     if (action === "test") {
         if (request.method !== "POST") {
             return privateJson({ error: "method not allowed" }, { status: 405 });
@@ -97,7 +116,7 @@ async function handleCredentialRequest(context, connectorId, action) {
             }, { status: 400 });
         }
         try {
-            const values = await opts.credentialVault.getAll(connectorId);
+            const values = await opts.credentialVault.getAll(connectorId, owner);
             const shape = storedCredentialShape(connector.credential, values);
             if (shape.state === "missing") {
                 return privateJson({
@@ -110,7 +129,7 @@ async function handleCredentialRequest(context, connectorId, action) {
                 return privateJson({ error: shape.message }, { status: 409 });
             }
             const storedValues = values;
-            const ctx = opts.registry.contextFor(connectorId, baseUrl);
+            const ctx = registry.contextFor(connectorId, baseUrl);
             const result = rule.mode === "multiple"
                 ? await connector.testCredentials(storedValues, ctx)
                 : await connector.testCredential(
@@ -131,9 +150,9 @@ async function handleCredentialRequest(context, connectorId, action) {
             return input.response;
         try {
             const metadata = input.input.kind === "single"
-                ? await opts.credentialVault.set(connectorId, input.input.value, admin.userId)
-                : await opts.credentialVault.setAll(connectorId, input.input.values, admin.userId);
-            await opts.registry.invalidateStored(connectorId);
+                ? await opts.credentialVault.set(connectorId, input.input.value, updatedBy, owner)
+                : await opts.credentialVault.setAll(connectorId, input.input.values, updatedBy, owner);
+            await registry.invalidateStored(connectorId);
             return privateJson({ credential: metadata });
         }
         catch (err) {
@@ -141,8 +160,8 @@ async function handleCredentialRequest(context, connectorId, action) {
         }
     }
     if (request.method === "DELETE") {
-        await opts.credentialVault.delete(connectorId);
-        await opts.registry.invalidateStored(connectorId);
+        await opts.credentialVault.delete(connectorId, owner);
+        await registry.invalidateStored(connectorId);
         return new Response(null, {
             status: 204,
             headers: {

package/dist/routes/mcp.js

@@ -4,6 +4,7 @@ import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError, } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
 import { instructionsFor } from "../skills.js";
+import { msg } from "../errors.js";
 import { authorize, } from "./shared.js";
 export const MCP_CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
@@ -329,14 +330,28 @@ export function createMcpRoute(opts) {
             throw error;
         }
         try {
-            const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
+            const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
             if (!authz.ok) {
                 return releaseAdmissionWithResponse(withMcpCors(authz.response), admission, request.signal);
             }
+            let scopedRegistry;
+            try {
+                scopedRegistry = opts.registry.scoped({
+                    connectorIds: authz.connectorIds,
+                    ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
+                    ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
+                });
+            }
+            catch (error) {
+                return releaseAdmissionWithResponse(withMcpCors(new Response(JSON.stringify({ error: msg(error) }), {
+                    status: 403,
+                    headers: { "Content-Type": "application/json" },
+                })), admission, request.signal);
+            }
             if (new URL(request.url).searchParams.has("toolkit")) {
                 return releaseAdmissionWithResponse(withMcpCors(toolkitRetired(opts.logger)), admission, request.signal);
             }
-            return releaseAdmissionWithResponse(withMcpCors(await serveMcp(request, opts, baseUrl, authz.actor, opts.registry, runtimeContext)), admission, request.signal);
+            return releaseAdmissionWithResponse(withMcpCors(await serveMcp(request, opts, baseUrl, authz.actor, scopedRegistry, runtimeContext)), admission, request.signal);
         }
         catch (error) {
             admission.release();

package/dist/routes/oauth.js

@@ -1,24 +1,38 @@
 import { oauthValueStorageKey } from "../auth/downstream-oauth.js";
 import { closeConnectorScope } from "../connector-scope.js";
 import { isSafeHttpUrl, resolveBranding } from "../ui.js";
-import { authorizeUiAdmin, isSameOrigin, loggableValue, msg, privateJson, } from "./shared.js";
+import { authorizeUiIdentity, isSameOrigin, loggableValue, msg, privateJson, } from "./shared.js";
 async function handleOAuthManagementRequest(context, connectorId) {
     const { request, baseUrl, opts, defer } = context;
     if (!isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "OAuth management", context.runtimeContext);
-    if (!admin.ok)
-        return admin.response;
-    const connector = opts.registry.getConnector(connectorId);
+    const authz = await authorizeUiIdentity(request, baseUrl, opts.auth, "OAuth management", context.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 connector = registry.getConnector(connectorId);
     if (!connector?.disconnectAuth || !connector.startAuth) {
         return privateJson({ error: "unknown OAuth connector" }, { status: 404 });
     }
+    if (connector.authScope === "personal" && !authz.principalKey) {
+        return privateJson({ error: "forbidden" }, { status: 403 });
+    }
     if (request.method !== "DELETE" && request.method !== "POST") {
         return privateJson({ error: "method not allowed" }, { status: 405 });
     }
     const requestScope = {};
-    const ctx = opts.registry.contextFor(connectorId, baseUrl, requestScope);
+    const ctx = registry.contextFor(connectorId, baseUrl, requestScope);
     try {
         let result;
         let operationError;
@@ -28,6 +42,9 @@ async function handleOAuthManagementRequest(context, connectorId) {
             }
             else {
                 result = await connector.startAuth(ctx, { force: true });
+                if (result.authorizationUrl) {
+                    await registry.bindOAuthHandoff(connectorId, result.authorizationUrl);
+                }
             }
         }
         catch (error) {
@@ -36,7 +53,7 @@ async function handleOAuthManagementRequest(context, connectorId) {
         // The old grant and its cached catalog are invalid after either operation,
         // including a partially failed physical cleanup whose epoch fence succeeded.
         try {
-            await opts.registry.invalidateStored(connectorId);
+            await registry.invalidateStored(connectorId);
         }
         catch (error) {
             operationError ??= error;
@@ -204,19 +221,36 @@ export async function routeOAuthCallback(context) {
     if (!code)
         return html("Missing authorization code.", 400, opts.branding);
     const id = path.slice("/oauth/callback/".length);
-    const connector = opts.registry.getConnector(id);
+    const state = url.searchParams.get("state");
+    const callbackTarget = await opts.registry.oauthCallbackView(id, state);
+    const callbackRegistry = callbackTarget?.registry;
+    const connector = callbackRegistry?.getConnector(id);
     // Safe to build before we know the id names anything: `contextFor` is a pure
     // constructor — a namespaced storage view over `conn:<id>:` and, only for a
     // connector that declares one, a lazy credential accessor. It neither throws
     // nor touches storage for an unknown id, which is what lets the refusals
     // below borrow it to equalize their cost.
-    const connectorContext = opts.registry.contextFor(id, baseUrl);
+    const connectorContext = callbackRegistry
+        ? callbackRegistry.contextFor(id, baseUrl)
+        : opts.registry.contextFor(id, baseUrl);
     const refused = () => html("Authorization could not be completed. Re-run authorization from " +
         "connecta and try again.", 400, opts.branding);
     if (!connector || !connector.finishAuth) {
         await equalizeRefusalCost(connectorContext);
         return refused();
     }
+    const expectedPrincipalKey = callbackTarget?.principalKey;
+    if (expectedPrincipalKey) {
+        const browserIdentity = await authorizeUiIdentity(context.request, baseUrl, opts.auth, "OAuth callback", context.runtimeContext, opts.identity);
+        if (browserIdentity.ok &&
+            browserIdentity.principalKey !== expectedPrincipalKey) {
+            opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
+                `${loggableValue(id)} with 400: the authenticated browser identity ` +
+                "did not start this personal authorization flow. No authorization " +
+                "code was exchanged.");
+            return refused();
+        }
+    }
     // CSRF / login-fixation guard: this route is intentionally public, so verify
     // the `state` matches the flow connecta started BEFORE exchanging the code.
     if (!connector.verifyState) {
@@ -228,7 +262,6 @@ export async function routeOAuthCallback(context) {
             "trying again.");
         return refused();
     }
-    const state = url.searchParams.get("state");
     let stateMatches;
     try {
         stateMatches = await connector.verifyState(state, connectorContext);
@@ -251,9 +284,20 @@ export async function routeOAuthCallback(context) {
             "connecta and try again.");
         return refused();
     }
+    if (connector.authScope === "personal") {
+        try {
+            await opts.registry.clearOAuthHandoff(id, state);
+        }
+        catch (err) {
+            opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
+                `${loggableValue(id)} with 500: its principal handoff could not be ` +
+                `consumed (${loggableValue(msg(err))}). No authorization code was exchanged.`);
+            return html("Authorization could not be completed.", 500, opts.branding);
+        }
+    }
     try {
         await connector.finishAuth(code, connectorContext, url.searchParams);
-        await opts.registry.invalidateStored(id);
+        await callbackRegistry.invalidateStored(id);
         return html(`Connected "${id}". You can close this window.`, 200, opts.branding);
     }
     catch (err) {