@zackbart/connecta 0.29.0 → 0.31.0

package/dist/meta-tools.js

@@ -1,3 +1,4 @@
+import { authorizationHandoff, bindAuthorizationHandoffs } from "./authorization-handoff.js";
 import { bindMcpClient } from "./mcp-client-context.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { z } from "zod";
@@ -6,18 +7,20 @@ import { boundedDiscoveryText, CatalogService, DEFAULT_SEARCH_LIMIT, DiscoveryPo
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, ConnectorCallError, msg } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
-import { MAX_EXECUTE_RESULT_CHARS, serializeResultText } from "./executor-result.js";
+import { guardExecuteResultValue, MAX_EXECUTE_RESULT_CHARS, serializeResultText } from "./executor-result.js";
 import { InvocationService } from "./invocation.js";
 import { isValidMaxResultBytes, MIN_MAX_RESULT_BYTES, resolveMaxResultBytes, } from "./registry.js";
 import { hasConnectorGuides, SkillsRegistry } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs } from "./timeout.js";
-import { AUTHORIZE_OUTPUT, CALL_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js";
+import { AUTHORIZE_OUTPUT, SEARCH_OUTPUT, SKILLS_OUTPUT } from "./meta-output.js";
 import { RESULT_TTL_SECONDS, resultKeys } from "./storage/keys.js";
 import { agentOutputOperations, sentSecretsForRequest } from "./sent-secrets.js";
 import { captureDownstreamInput } from "./downstream-input.js";
+import { PROGRAM_RESULT_WIRE_BYTES } from "./program-result.js";
 export { MAX_DESCRIBE_ADDRESSES, MAX_DISCOVERY_RESULT_BYTES, MAX_SEARCH_LIMIT };
 const enc = new TextEncoder();
-const dec = new TextDecoder();
+// Each page is a slice of payload bytes, so a leading U+FEFF is data.
+const dec = new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
 export function jsonResult(obj, text = JSON.stringify(obj)) {
     return {
         content: [{ type: "text", text }],
@@ -142,6 +145,23 @@ function base64Of(bytes) {
 }
 /** Opens a write's notice, ahead of any paging instruction. */
 const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see its result.";
+/** UTF-8 cannot represent lone UTF-16 surrogates without changing them. */
+function isWellFormedText(text) {
+    const native = String.prototype.isWellFormed;
+    if (native)
+        return native.call(text);
+    for (let at = 0; at < text.length; at++) {
+        const unit = text.charCodeAt(at);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = text.charCodeAt(++at);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 /**
  * Offers a read the route meta-tools.md prefers for finding something in it:
  * repeat the call inside a program and reduce it there. Paging comes second,
@@ -153,6 +173,8 @@ const WRITE_ALREADY_RAN = "This write already ran: do not call it again to see i
 const READ_REDUCE_FIRST = "To find something specific, repeat this read inside execute_code with connecta.call and filter or search the result there, returning only what matters";
 function pagingHint(results, totalBytes, preview) {
     if (!results.write) {
+        if (results.binding.program)
+            return "filter/map/slice data inside execute_code and return only what you need; page this completed return with connecta.result using nextAction.";
         const [shown, full] = preview.kind === "prefix"
             ? [`Bytes 0-${preview.bytes} of ${totalBytes} follow.`, "to read it in full, page the rest"]
             : preview.kind === "text-of-envelope"
@@ -177,8 +199,17 @@ function pagingHint(results, totalBytes, preview) {
  * documentation/meta-tools.md#result-representation). It is one compact JSON
  * line with no raw newline, so the preview starts after the first `\n`.
  */
-async function stashResult(bytes, results, preview) {
+async function stashResult(bytes, results, preview, rawText) {
     const totalBytes = bytes.length;
+    // Direct pages promise offsets into the original UTF-8 text. JSON-escaping
+    // raw text would change that contract; never stash the encoder's replacement
+    // characters as if they were the completed call's output.
+    if (rawText !== undefined && !isWellFormedText(rawText))
+        return {
+            truncated: true,
+            totalBytes,
+            hint: `${results.write ? WRITE_ALREADY_RAN + " " : ""}Paging is unavailable: text contains unpaired surrogates and can't be paged as text; request the value as JSON (value mode or a JSON-returning call) to recover it.`,
+        };
     if (!results.pageable)
         return {
             truncated: true,
@@ -238,6 +269,74 @@ async function stashResult(bytes, results, preview) {
         },
     };
 }
+/** Program calls use the direct-call envelope, ledger, expiry and authority. */
+export async function pageProgramResult(registry, baseUrl, resolved, value, format, secrets, trust, requestScope, wireBytes = PROGRAM_RESULT_WIRE_BYTES) {
+    const data = secrets.redact(value);
+    const wire = JSON.stringify({ data, format });
+    if (enc.encode(wire).length <= wireBytes)
+        return { data, format };
+    const text = secrets.text(format === "text" ? String(data) : serializeResultText(data));
+    const bytes = enc.encode(text);
+    const write = resolved.definition.classification !== "read";
+    const notice = await stashResult(bytes, {
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            connector: resolved.connector.id,
+            tool: resolved.definition.name,
+            classification: write ? "write" : "read",
+        },
+        write,
+        cap: resolveMaxResultBytes(resolved.connector.maxResultBytes, registry.maxResultBytes),
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(registry.contextFor(resolved.connector.id, baseUrl, requestScope).logger, "result paging unavailable", failureRecord({ connector: resolved.connector.id, tool: resolved.definition })),
+    }, { kind: "none" }, format === "text" ? text : undefined);
+    return {
+        format: "paged",
+        valueFormat: format,
+        ...(notice.resultId ? { resultId: notice.resultId } : {}),
+        totalBytes: bytes.length,
+        truncated: true,
+        hint: notice.resultId
+            ? `${write ? WRITE_ALREADY_RAN + " " : ""}Page this result with connecta.result(handle); do not repeat the call for output.`
+            : notice.hint,
+    };
+}
+/** Program returns share the direct stash, with all host-admitted call dependencies. */
+export async function guardProgramReturn(value, registry, baseUrl, dependencies, secrets, trust, logger, maxChars, completedWrite) {
+    const serialized = serializeResultText(value);
+    if (serialized.length <= maxChars)
+        return value;
+    const text = secrets.text(serialized);
+    const bytes = enc.encode(text);
+    const write = dependencies.some((dependency) => dependency.classification === "write");
+    const cap = Math.min(registry.maxResultBytes, ...dependencies.map((dependency) => resolveMaxResultBytes(registry.getConnector(dependency.connector)?.maxResultBytes, registry.maxResultBytes)));
+    const results = {
+        secrets,
+        pageable: !write || trust === "trusted",
+        binding: {
+            identity: registry.resultIdentity(),
+            baseUrl,
+            classification: write ? "write" : "read",
+            program: dependencies,
+        },
+        write: completedWrite,
+        cap,
+        set: (id, chunks, ttl) => registry.stashResult(id, chunks, ttl),
+        warn: () => logFailure(logger, "result paging unavailable", failureRecord({})),
+    };
+    const notice = await stashResult(bytes, results, { kind: "none" }, text);
+    // Put the entire recovery route ahead of the preview in both response forms.
+    // A client retaining only the first 2,000 characters still sees the action.
+    if (notice.resultId) {
+        const base = { ...notice, totalChars: text.length, preview: "" };
+        const budget = Math.max(0, maxChars - JSON.stringify(base).length);
+        return { ...base, preview: escapedHeadOf(bytes, Math.min(512, budget)) };
+    }
+    const fallback = guardExecuteResultValue(secrets.redact(value), maxChars, notice.hint);
+    return { truncated: true, totalChars: fallback.totalChars, hint: fallback.hint, preview: fallback.preview };
+}
 /** The first `cap` bytes of `bytes`, ending on a character boundary. */
 function headOf(bytes, cap) {
     return bytes.subarray(0, alignEndToCharBoundary(bytes, 0, cap, bytes.length));
@@ -246,7 +345,6 @@ function headOf(bytes, cap) {
 function noticeFirst(notice, preview) {
     return {
         content: [{ type: "text", text: `${JSON.stringify(notice)}\n${preview}` }],
-        structuredContent: { ...notice, format: "text" },
     };
 }
 /**
@@ -264,6 +362,10 @@ async function guardEncoded(text, bytes, results, cap) {
             truncated: false,
         };
     }
+    if (!isWellFormedText(text)) {
+        const notice = await stashResult(bytes, results, { kind: "none" }, text);
+        return { result: noticeFirst(notice, ""), truncated: true };
+    }
     const head = headOf(bytes, cap);
     const notice = await stashResult(bytes, results, {
         kind: "prefix",
@@ -380,13 +482,6 @@ async function guardContent(content, results, cap) {
         truncated: true,
     };
 }
-/**
- * The sentence that closes the OAuth handoff, telling the operator's agent how
- * to confirm the flow landed through the one surface it can call.
- */
-function oauthFollowUp(connectorId) {
-    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
-}
 /**
  * Every meta-tool handler over a registry, one per registered tool. Exported for
  * direct testing; registerMetaTools() wires the six explicit tools onto an
@@ -415,6 +510,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     // identity lets remote connectors reuse one downstream client inside that
     // request without leaking request-bound I/O into the next one.
     const requestScope = opts.requestScope ?? {};
+    if (opts.canManageAuth || opts.oauthConnectUrl || opts.credentialHandoffUrl || opts.oauthConnectUnavailable) {
+        bindAuthorizationHandoffs(requestScope, (connector) => authorizationHandoff(registry, baseUrl, requestScope, opts, { connector }));
+    }
     const sentSecrets = sentSecretsForRequest(requestScope);
     const skills = new SkillsRegistry(registry, baseUrl, {
         requestScope,
@@ -498,12 +596,14 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                         ];
                     }
                     const guarded = await guardContent(content, results, cap);
-                    guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
+                    // Native blocks and bounded previews are the result. A format-only
+                    // structuredContent hides them in clients that prefer that field.
+                    guarded.result._meta = { "dev.connecta/format": format };
                     return processed(guarded.result, guarded.truncated);
                 }
                 const value = result;
                 const guarded = await guardText(serializeResultText(value), results, cap);
-                guarded.result.structuredContent = { ...guarded.result.structuredContent, format };
+                guarded.result._meta = { "dev.connecta/format": format };
                 return processed(guarded.result, guarded.truncated, { value });
             },
             activityFriction: (processed) => processed.friction,
@@ -615,6 +715,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
+            if (args.page !== undefined && (!Number.isSafeInteger(args.page) || args.page < 0 || args.offset !== undefined)) {
+                return errorResult("Use a whole page >= 0, without offset.");
+            }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
@@ -668,21 +771,48 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 binding.identity.principal !== identity.principal ||
                 binding.identity.endpoint !== identity.endpoint ||
                 binding.identity.origin !== identity.origin ||
-                typeof binding.connector !== "string" ||
-                typeof binding.tool !== "string" ||
+                (binding.program === undefined
+                    ? typeof binding.connector !== "string" || typeof binding.tool !== "string"
+                    : !Array.isArray(binding.program) ||
+                        binding.program.some((dependency) => !dependency ||
+                            typeof dependency.connector !== "string" ||
+                            (dependency.tool !== undefined && typeof dependency.tool !== "string") ||
+                            (dependency.access !== undefined &&
+                                (dependency.access !== "catalog" || dependency.classification !== "read")) ||
+                            !["read", "write"].includes(dependency.classification))) ||
                 !["read", "write"].includes(binding.classification))
                 return denied();
             const allowed = async () => {
                 options.signal?.throwIfAborted();
                 try {
-                    const address = `${binding.connector}.${binding.tool}`;
-                    if (!(await registry.recheckResultAccess(address, binding.classification, options.signal)))
+                    if (binding.program &&
+                        !(await registry.recheckResultAccess(undefined, binding.classification, options.signal)))
                         return false;
-                    if (!registry.getConnector(binding.connector))
+                    if (binding.classification === "write" && opts.trust !== "trusted")
                         return false;
-                    const tools = await registry.getTools(binding.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
-                    const tool = tools.find((tool) => tool.name === binding.tool);
-                    return Boolean(tool && ((binding.classification === "read" && tool.classification === "read") || opts.trust === "trusted"));
+                    const dependencies = binding.program ?? [binding];
+                    for (const dependency of dependencies) {
+                        const address = dependency.tool === undefined ? dependency.connector : `${dependency.connector}.${dependency.tool}`;
+                        if (!(await registry.recheckResultAccess(address, dependency.classification, options.signal, dependency.access)))
+                            return false;
+                        if (dependency.tool === undefined) {
+                            if (dependency.access === "catalog"
+                                ? !registry.getConnector(dependency.connector)
+                                : !registry.getResourceConnector(dependency.connector))
+                                return false;
+                            continue;
+                        }
+                        if (!registry.getConnector(dependency.connector))
+                            return false;
+                        const tools = await registry.getTools(dependency.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
+                        const tool = tools.find((tool) => tool.name === dependency.tool);
+                        if (!tool ||
+                            !(dependency.access === "catalog" ||
+                                (dependency.classification === "read" && tool.classification === "read") ||
+                                opts.trust === "trusted"))
+                            return false;
+                    }
+                    return true;
                 }
                 catch {
                     options.signal?.throwIfAborted();
@@ -691,7 +821,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             };
             if (!(await allowed()))
                 return denied();
-            const requestedOffset = args.offset ?? 0;
+            opts.onResultRead?.(binding.program ?? [binding]);
+            let requestedOffset = args.offset ?? 0;
             const cap = Number(header[4]);
             if (!isValidMaxResultBytes(cap))
                 return denied();
@@ -708,6 +839,12 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     chunkBytes < 3 ||
                     chunkBytes % 3 !== 0)
                     return denied();
+                if (args.page !== undefined) {
+                    // At least one complete UTF-8 codepoint per nominal window. Adjacent
+                    // pages align both edges backwards, so no character repeats or vanishes.
+                    const width = Math.max(4, maxBytes);
+                    requestedOffset = Math.min(total, Math.min(args.page, Math.ceil(total / width)) * width);
+                }
                 start = Math.floor(Math.max(0, Math.min(requestedOffset, total) - 3) / 3) * 3;
                 const end = Math.min(total, requestedOffset + maxBytes + 4);
                 bytes = new Uint8Array(Math.max(0, end - start));
@@ -744,7 +881,10 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // never split across pages (which would emit U+FFFD on both sides).
             // `nextOffset` is this aligned end, so it is a valid boundary for the
             // next call and paging reassembles the original byte-for-byte.
-            const end = start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start);
+            const end = args.page === undefined
+                ? start + alignEndToCharBoundary(bytes, offset - start, offset - start + maxBytes, total - start)
+                : start +
+                    alignStartToCharBoundary(bytes, Math.min(total - start, requestedOffset - start + Math.max(4, maxBytes)));
             const slice = dec.decode(bytes.subarray(offset - start, end - start));
             const hasMore = end < total;
             // The same notice-first shape as a truncated call: one line of header,
@@ -766,76 +906,8 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             return page;
         },
         async authorizeConnector(args) {
-            const connector = registry.getConnector(args.connector);
-            if (!connector) {
-                return errorResult(`Unknown connector "${boundedEchoText(args.connector)}"`);
-            }
-            if (!connector.startAuth) {
-                if (!connector.credential) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: `Connector "${connector.id}" declares neither downstream OAuth ` +
-                            "nor an operator-managed credential slot. Update the connector " +
-                            "or deployment configuration before retrying.",
-                    });
-                }
-                const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
-                if (!ctx.credential || !opts.credentialHandoffUrl) {
-                    return jsonResult({
-                        connector: connector.id,
-                        recovery: "unavailable",
-                        message: "Credential recovery needs both a vault and the optional UI. Configure " +
-                            "vault and ui in deployment code, then call " +
-                            "authorize_connector again.",
-                    });
-                }
-                const fields = connector.credential.fields?.map((field) => ({
-                    name: field.name,
-                    guidance: field.description ?? field.label,
-                })) ?? [
-                    {
-                        name: "value",
-                        guidance: connector.credential.description ?? connector.credential.label,
-                    },
-                ];
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "operator_config",
-                    credential: {
-                        label: connector.credential.label,
-                        fields,
-                    },
-                    operatorUrl: opts.credentialHandoffUrl,
-                    instructions: "Have the operator open operatorUrl, set and test the credential, " +
-                        "then retry the original call. No redeploy is needed. " +
-                        (connector.authScope === "personal"
-                            ? "Credential mutation requires the signed-in principal who owns this connection."
-                            : "Shared credential mutation requires a signed-in human with access to this connector."),
-                });
-            }
-            if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "unavailable",
-                    message: opts.oauthConnectUnavailable ??
-                        "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
-                });
-            if (!opts.canManageAuth?.(connector.id))
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "unavailable",
-                    message: "Your identity is not permitted to manage authentication for this connection.",
-                });
             try {
-                return jsonResult({
-                    connector: connector.id,
-                    recovery: "oauth",
-                    status: "auth_required",
-                    authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
-                    instructions: "Open authorizationUrl in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
-                        oauthFollowUp(connector.id),
-                });
+                return jsonResult(await authorizationHandoff(registry, baseUrl, requestScope, opts, args));
             }
             catch (err) {
                 return errorResult(msg(err));
@@ -967,7 +1039,7 @@ export function registerMetaTools(server, registry, ctx) {
     server.registerTool("call_tool", {
         description: CALL_DESC,
         inputSchema: CALL_INPUT,
-        outputSchema: CALL_OUTPUT,
+        // Default mode returns native content, so no structured result is promised.
         // call_tool admits only tools that are themselves explicitly read-only;
         // anything else is refused and routed to call_destructive_tool.
         annotations: READ_ONLY_REMOTE,
@@ -980,7 +1052,6 @@ export function registerMetaTools(server, registry, ctx) {
     server.registerTool("call_destructive_tool", {
         description: describedFor(registry, CALL_DESTRUCTIVE_DESC, "destructive"),
         inputSchema: CALL_DESTRUCTIVE_INPUT,
-        outputSchema: CALL_OUTPUT,
         annotations: {
             destructiveHint: true,
             readOnlyHint: false,

package/dist/oauth-handoff.js

@@ -1,6 +1,66 @@
 import { oauthConnectKeys } from "./storage/keys.js";
 const HANDOFF_TTL_MS = 15 * 60_000;
 const INTERACTIVE_OAUTH_REQUIRED = "An interactive provider (Clerk or Cloudflare Access) is required to connect OAuth connectors.";
+// Length-prefixed fields avoid JSON keys and escaping without reserving any
+// character in an identity. This is an opaque wire encoding, not encryption.
+function encodeHandoff(h) {
+    return [
+        h.connector,
+        h.owner,
+        h.principal,
+        h.origin,
+        h.expiresAt.toString(36),
+        h.nonce,
+        h.force ? "1" : "0",
+        h.after ?? "",
+    ]
+        .map((field) => `${field.length}:${field}`)
+        .join("");
+}
+function decodeHandoff(value) {
+    const fields = [];
+    let offset = 0;
+    while (offset < value.length && fields.length < 8) {
+        const colon = value.indexOf(":", offset);
+        const lengthText = value.slice(offset, colon);
+        if (colon < offset || !/^(0|[1-9][0-9]*)$/.test(lengthText))
+            throw new Error("Invalid handoff field");
+        const length = Number(lengthText);
+        offset = colon + 1;
+        if (!Number.isSafeInteger(length) || length > value.length - offset)
+            throw new Error("Invalid handoff length");
+        fields.push(value.slice(offset, offset + length));
+        offset += length;
+    }
+    const [connector, owner, principal, origin, expiry, nonce, force, after] = fields;
+    if (fields.length !== 8 || offset !== value.length || !/^[0-9a-z]+$/.test(expiry) || !/^[01]$/.test(force))
+        throw new Error("Invalid handoff fields");
+    return {
+        connector: connector,
+        owner: owner,
+        principal: principal,
+        origin: origin,
+        expiresAt: parseInt(expiry, 36),
+        nonce: nonce,
+        force: force === "1",
+        ...(after ? { after } : {}),
+    };
+}
+function encodeSegment(value) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(value))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeSegment(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error("Invalid handoff encoding");
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/"));
+    const decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+    if (encodeSegment(decoded) !== value)
+        throw new Error("Noncanonical handoff encoding");
+    return decoded;
+}
 export function oauthConnectUnavailable(opts) {
     if (!opts.config.auth.some((provider) => provider.interactiveOperator &&
         (provider.uiAuth?.kind === "clerk" || provider.uiAuth?.kind === "cloudflare-access"))) {
@@ -34,10 +94,13 @@ export async function oauthConnectLink(opts, baseUrl, connectorId, principal, fo
     const vault = opts.config.vault;
     if (opaque && (!vault.seal || !vault.open))
         throw new Error("URL elicitation requires a sealing credential vault.");
+    const compact = encodeHandoff(handoff);
     const payload = opaque
-        ? `v2:${btoa(await vault.seal(connectorId, "connecta:connect-link:v2", JSON.stringify(handoff)))}`
-        : btoa(JSON.stringify(handoff));
-    const signature = await opts.config.vault.signOAuthHandoff(payload);
+        ? `v4.${encodeSegment(await vault.seal(connectorId, "connecta:connect-link:v4", compact))}`
+        : `v3.${encodeSegment(compact)}`;
+    // Preserve the vault's entire signature and its representation, including
+    // custom vaults, while keeping every URL segment unpadded base64url.
+    const signature = encodeSegment(await vault.signOAuthHandoff(payload));
     const url = new URL(`/connect/${connectorId}`, baseUrl);
     url.searchParams.set("h", `${payload}.${signature}`);
     return { url: url.toString(), nonce: handoff.nonce };
@@ -63,15 +126,29 @@ export async function claimAuthRetry(opts, baseUrl, id, nonce) {
 export async function verifyOAuthHandoff(opts, baseUrl, connectorId, token) {
     if (!token || token.length > 4096)
         return null;
-    const [payload, signature, ...rest] = token.split(".");
-    if (!payload || !signature || rest.length)
-        return null;
     try {
-        if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, signature)))
-            return null;
-        const h = JSON.parse(payload.startsWith("v2:")
-            ? await opts.config.vault.open(connectorId, "connecta:connect-link:v2", atob(payload.slice(3)))
-            : atob(payload));
+        const parts = token.split(".");
+        let h;
+        if (parts.length === 3 && (parts[0] === "v3" || parts[0] === "v4")) {
+            const [version, body, signature] = parts;
+            const payload = `${version}.${body}`;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, decodeSegment(signature))))
+                return null;
+            const decoded = decodeSegment(body);
+            h = decodeHandoff(version === "v4" ? await opts.config.vault.open(connectorId, "connecta:connect-link:v4", decoded) : decoded);
+        }
+        else {
+            // Keep pre-upgrade JSON and sealed v2 links until their original expiry.
+            // Authenticate their exact original text; never normalize before verifying.
+            const [payload, signature, ...rest] = parts;
+            if (!payload || !signature || rest.length)
+                return null;
+            if (!(await opts.config.vault?.verifyOAuthHandoff?.(payload, signature)))
+                return null;
+            h = JSON.parse(payload.startsWith("v2:")
+                ? await opts.config.vault.open(connectorId, "connecta:connect-link:v2", atob(payload.slice(3)))
+                : atob(payload));
+        }
         const connector = opts.registry.getConnector(connectorId);
         if (!connector ||
             h.connector !== connectorId ||