@zackbart/connecta 0.26.2 → 0.26.3

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this package are documented here.
 
 ## Unreleased
 
+## 0.26.3 — 2026-09-28
+
+This patch lets downstream OAuth connections use a public client metadata
+URL when a server supports URL-based client IDs but restricts dynamic
+registration. Existing OAuth configurations keep their current behavior.
+The Node template now pins 0.26.3.
+
+### Added
+
+- `remoteMcp` OAuth auth accepts `clientMetadataUrl` and default `scope`.
+  The SDK negotiates URL-based client IDs, falling back to dynamic registration
+  when unsupported. Existing PKCE, issuer binding, encrypted storage, refresh,
+  and disconnect remain in use. Invalid settings fail at construction.
+
 ## 0.26.2 — 2026-09-27
 
 This patch restores named client tokens as an optional auth module. Deployments

package/dist/auth/downstream-oauth.js

@@ -850,6 +850,8 @@ export class KvOAuthProvider {
     signal;
     clientBinding;
     onReset;
+    scope;
+    clientMetadataUrl;
     /**
      * The reset generation this provider's flow started under. Every OAuth value
      * it writes carries this epoch, so a late write can land after a reset without
@@ -869,7 +871,9 @@ export class KvOAuthProvider {
     /** Stable connector configuration bound to dynamically registered clients. */
     clientBinding, 
     /** Request-local observer so the operator route drains every reset it began. */
-    onReset) {
+    onReset, 
+    /** SDK uses this only when the authorization server advertises support. */
+    clientMetadataUrl, scope) {
         this.connectorId = connectorId;
         this.storage = storage;
         this.redirectUri = redirectUri;
@@ -879,6 +883,9 @@ export class KvOAuthProvider {
         this.signal = signal;
         this.clientBinding = clientBinding;
         this.onReset = onReset;
+        this.scope = scope;
+        if (clientMetadataUrl !== undefined)
+            this.clientMetadataUrl = clientMetadataUrl;
     }
     /**
      * Stamp the force-reauth generation the current connect flow started under.
@@ -1339,6 +1346,7 @@ export class KvOAuthProvider {
             grant_types: ["authorization_code", "refresh_token"],
             response_types: ["code"],
             token_endpoint_auth_method: "none",
+            ...(this.scope !== undefined ? { scope: this.scope } : {}),
         };
     }
     async clientInformation(ctx) {

package/dist/connectors/remote-mcp.d.ts

@@ -38,6 +38,10 @@ export type RemoteMcpAuth = {
     headers: Record<string, string>;
 } | RemoteMcpCredentialAuth | {
     type: "oauth";
+    /** Public HTTPS client metadata document, for servers supporting URL-based client IDs. */
+    clientMetadataUrl?: string;
+    /** Space-separated default scopes when the resource server does not advertise them. */
+    scope?: string;
 };
 /**
  * Apply a maintained provider's slot copy and header framing to credential

package/dist/connectors/remote-mcp.js

@@ -396,6 +396,22 @@ function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
  * server or hide other connectors).
  */
 export function remoteMcp(id, opts) {
+    const clientMetadataUrl = opts.auth?.type === "oauth" ? opts.auth.clientMetadataUrl : undefined;
+    const oauthScope = opts.auth?.type === "oauth" ? opts.auth.scope : undefined;
+    if (oauthScope !== undefined && !/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(oauthScope)) {
+        throw new Error(`[connecta] connector "${id}" OAuth scope must contain space-separated scope tokens.`);
+    }
+    if (clientMetadataUrl !== undefined) {
+        let valid = false;
+        try {
+            const url = new URL(clientMetadataUrl);
+            valid = url.protocol === "https:" && url.pathname !== "/" &&
+                !url.username && !url.password && !url.hash;
+        }
+        catch { /* Invalid configuration is rejected below without echoing its value. */ }
+        if (!valid)
+            throw new Error(`[connecta] connector "${id}" clientMetadataUrl must be an HTTPS URL with a non-root path, without credentials or a fragment.`);
+    }
     if (opts.authScope === "personal" && opts.auth?.type === "headers") {
         throw new Error(`[connecta] connector "${id}" cannot combine authScope "personal" ` +
             "with static headers. Use credential or OAuth auth so each principal " +
@@ -597,11 +613,13 @@ export function remoteMcp(id, opts) {
                 grant_types: ["authorization_code", "refresh_token"],
                 response_types: ["code"],
                 token_endpoint_auth_method: "none",
+                ...(oauthScope !== undefined ? { scope: oauthScope } : {}),
             },
             authScope: opts.authScope ?? "shared",
             versionNegotiation: opts.versionNegotiation ?? "auto",
             redirects: opts.redirects ?? "none",
-        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset));
+            clientMetadataUrl,
+        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), clientMetadataUrl, oauthScope);
         if (state)
             state.provider = provider;
         return provider;

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.26.2";
+export declare const CONNECTA_VERSION = "0.26.3";

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.26.2";
+export const CONNECTA_VERSION = "0.26.3";

package/documentation/auth.md

@@ -615,3 +615,26 @@ present, must match that owner and may then manage the connector, while an
 interactive provider's explicit 403 still refuses the flow. See
 [meta-tools](./meta-tools.md#authorization-recovery) for the recovery shapes a
 caller actually receives.
+
+## URL-based downstream OAuth clients
+
+`remoteMcp` accepts `auth: { type: "oauth", clientMetadataUrl, scope }`.
+`clientMetadataUrl` names a public HTTPS OAuth client metadata document with a
+non-root path. It must not contain credentials or a fragment. The document
+must include its own URL as `client_id`, the deployment's exact
+`/oauth/callback/<connector-id>` in `redirect_uris`, authorization-code and
+refresh-token grants, and `token_endpoint_auth_method: "none"`. Hosting that
+public document belongs to the deployment; Connecta does not expose a public
+route through inbound authentication.
+
+The SDK uses the URL as the client ID only when the authorization server
+advertises `client_id_metadata_document_supported`. Otherwise it keeps the
+existing dynamic registration flow. State validation, PKCE, issuer binding,
+encrypted token storage, refresh, and disconnect follow the same code paths.
+The metadata URL and scopes participate in the saved-client configuration
+binding, so restarting after either changes cannot reuse an old registration.
+
+`scope` supplies space-separated default OAuth scopes through client metadata.
+A downstream challenge or protected-resource scope declaration takes precedence,
+and the SDK adds `offline_access` when advertised for refresh-token grants.
+Omitting both settings preserves the existing discovery and registration flow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of eight meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.26.2",
+    "@zackbart/connecta": "0.26.3",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {