@sentropic/h2a-cli 0.48.0 → 0.55.0

package/dist/runtime/mcp-http/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/runtime/mcp-http/app.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAGnF,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,yBAAyB,CAAC;IACzC,WAAW,EAAE,oBAAoB,CAAC;IAClC,2FAA2F;IAC3F,YAAY,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,2FAA2F;QAC3F,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;KAC3C,CAAC;CACH;AAQD,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAmIzD"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/runtime/mcp-http/app.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEtF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAGnF,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,yBAAyB,CAAC;IACzC,WAAW,EAAE,oBAAoB,CAAC;IAClC,2FAA2F;IAC3F,YAAY,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,2FAA2F;QAC3F,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;KAC3C,CAAC;CACH;AAQD,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA2JzD"}

package/dist/runtime/mcp-http/app.js

@@ -23,10 +23,36 @@ export function createHostedApp(deps) {
     if (deps.oauthConfig.brokerMode && deps.brokerLogin) {
         app.route("/", buildBrokerRoutes({
             brokerLogin: deps.brokerLogin,
+            // Gate the claude.ai request BEFORE delegating to 39-auth: the broker has
+            // no consent secret, so an unregistered redirect_uri / missing PKCE must
+            // be rejected here, else an attacker collects the victim's code.
+            validateClaudeaiAuthorize: async (claudeai) => {
+                if (!claudeai.client_id)
+                    return { ok: false, error: "invalid_request", description: "missing client_id" };
+                const client = await deps.oauthProvider.clientsStore.getClient(claudeai.client_id);
+                if (!client)
+                    return { ok: false, error: "invalid_client", description: "unknown client_id" };
+                const registered = client.redirect_uris ?? [];
+                if (!claudeai.redirect_uri || !registered.includes(claudeai.redirect_uri)) {
+                    return { ok: false, error: "invalid_request", description: "redirect_uri is not registered for this client" };
+                }
+                if (claudeai.response_type !== undefined && claudeai.response_type !== "code") {
+                    return { ok: false, error: "unsupported_response_type", description: "only response_type=code is supported" };
+                }
+                if (!claudeai.code_challenge || claudeai.code_challenge_method !== "S256") {
+                    return { ok: false, error: "invalid_request", description: "PKCE code_challenge (S256) is required" };
+                }
+                return { ok: true };
+            },
             issueClaudeaiCode: async (claudeai, ctx) => {
                 const client = await deps.oauthProvider.clientsStore.getClient(claudeai.client_id);
                 if (!client)
                     throw new Error("unknown client_id");
+                // Defense-in-depth: re-check the redirect_uri belongs to the client
+                // before minting the code (never trust the carried-through value alone).
+                if (!claudeai.redirect_uri || !(client.redirect_uris ?? []).includes(claudeai.redirect_uri)) {
+                    throw new Error("redirect_uri is not registered for this client");
+                }
                 // Bind the 39-auth subject to the issued code: it rides code→token so
                 // verifyAccessToken restores it and /mcp serves rootForSub(base, sub).
                 const code = await deps.oauthProvider.issueAuthorizationCode(client, {

package/dist/runtime/mcp-http/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/runtime/mcp-http/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/runtime/mcp-http/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAA6B,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAmChD,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,qBAAqB,GAAG,qFAAqF,IAAI,CAAC,WAAW,CAAC,mBAAmB,GAAG,CAAC;IAE3J,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACjD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEhD,+EAA+E;IAC/E,0EAA0E;IAC1E,iFAAiF;IACjF,IAAI,IAAI,CAAC,WAAW,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACpD,GAAG,CAAC,KAAK,CACP,GAAG,EACH,iBAAiB,CAAC;YAChB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,0EAA0E;YAC1E,yEAAyE;YACzE,iEAAiE;YACjE,yBAAyB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;gBAC5C,IAAI,CAAC,QAAQ,CAAC,SAAS;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC;gBAC1G,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACnF,IAAI,CAAC,MAAM;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC;gBAC7F,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;gBAC9C,IAAI,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;oBAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,gDAAgD,EAAE,CAAC;gBAChH,CAAC;gBACD,IAAI,QAAQ,CAAC,aAAa,KAAK,SAAS,IAAI,QAAQ,CAAC,aAAa,KAAK,MAAM,EAAE,CAAC;oBAC9E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2BAA2B,EAAE,WAAW,EAAE,sCAAsC,EAAE,CAAC;gBAChH,CAAC;gBACD,IAAI,CAAC,QAAQ,CAAC,cAAc,IAAI,QAAQ,CAAC,qBAAqB,KAAK,MAAM,EAAE,CAAC;oBAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,wCAAwC,EAAE,CAAC;gBACxG,CAAC;gBACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACtB,CAAC;YACD,iBAAiB,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE;gBACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACnF,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBAClD,oEAAoE;gBACpE,yEAAyE;gBACzE,IAAI,CAAC,QAAQ,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;oBAC5F,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;gBACpE,CAAC;gBACD,sEAAsE;gBACtE,uEAAuE;gBACvE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,sBAAsB,CAAC,MAAM,EAAE;oBACnE,WAAW,EAAE,QAAQ,CAAC,YAAY;oBAClC,aAAa,EAAE,QAAQ,CAAC,cAAc,IAAI,EAAE;oBAC5C,MAAM,EAAE,CAAC,sBAAsB,CAAC;oBAChC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACpD,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACrC,CAAC,CAAC;gBACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;gBAChD,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACxC,IAAI,QAAQ,CAAC,KAAK;oBAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAEvE,oEAAoE;IACpE,MAAM,WAAW,GAAG,UAAU,CAAC;QAC7B,WAAW,EAAE,KAAK,EAAE,KAAa,EAAoB,EAAE;YACrD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;gBAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QACD,sBAAsB,EAAE,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC,qBAAqB,EAAE;QAC9E,2BAA2B,EAAE,EAAE,qBAAqB,EAAE,GAAG,EAAE,CAAC,qBAAqB,EAAE;KACpF,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEnD,8EAA8E;IAC9E,2EAA2E;IAC3E,gDAAgD;IAChD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IACzE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAqB,CAAC;IACnD,MAAM,eAAe,GAAG,CAAC,IAAY,EAAa,EAAE;QAClD,IAAI,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,CAAC,OAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC1C,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,iBAAiB,GAAG,KAAK,EAAE,CAAU,EAA+B,EAAE;QAC1E,IAAI,CAAC,WAAW;YAAE,OAAO,SAAS,CAAC;QACnC,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7E,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACnE,OAAO,UAAU,CAAC,IAAI,CAAC,OAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,CAAU,EAAE,EAAE,CAC/B,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,mCAAmC,EAAE,EAAE,GAAG,CAAC,CAAC;IAElG,MAAM,UAAU,GAAG,KAAK,EAAE,CAAU,EAAE,EAAE;QACtC,IAAI,UAA8B,CAAC;QACnC,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;QAED,MAAM,kBAAkB,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC1D,IAAI,OAAO,GAAG,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEhF,wEAAwE;QACxE,uCAAuC;QACvC,IAAI,OAAO,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU;YAAE,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;QAEtE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,OAAmC,CAAC;YACxC,MAAM,SAAS,GAAG,IAAI,uBAAuB,CAAC;gBAC5C,kBAAkB,EAAE,IAAI;gBACxB,kBAAkB,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;gBACtC,oBAAoB,EAAE,CAAC,SAAS,EAAE,EAAE;oBAClC,IAAI,OAAO;wBAAE,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBAChD,CAAC;gBACD,eAAe,EAAE,CAAC,SAAS,EAAE,EAAE;oBAC7B,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBAC7B,CAAC;aACF,CAAC,CAAC;YACH,OAAO,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;YACzE,sEAAsE;YACtE,4EAA4E;YAC5E,MAAM,IAAI,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;YACxF,MAAM,MAAM,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;YAC1C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChC,OAAO,GAAG,OAAO,CAAC;QACpB,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QACrD,OAAO,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC,CAAC;IAEF,mFAAmF;IACnF,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAEzC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/runtime/mcp-http/oauth/broker-routes.d.ts

@@ -22,6 +22,22 @@ export interface BrokerRoutesDeps {
         sub: string;
         root: string;
     }) => string | Promise<string>;
+    /**
+     * Validate the claude.ai /authorize request BEFORE delegating to 39-auth. The
+     * single-tenant flow is gated by the consent secret; the broker has none, so
+     * an unvalidated `redirect_uri` would let an attacker craft
+     * `/authorize?client_id=<real>&redirect_uri=https://evil&code_challenge=<theirs>`,
+     * have the victim log in at 39-auth, and collect a code at their URL bound to
+     * the victim's sub. This MUST reject an unregistered redirect_uri / bad PKCE
+     * before the login starts. Returns ok, or an error rendered as 400.
+     */
+    readonly validateClaudeaiAuthorize?: (claudeai: Record<string, string>) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+        description: string;
+    }>;
     /** Callback path registered at 39-auth. Default `/oidc/callback`. */
     readonly callbackPath?: string;
 }

package/dist/runtime/mcp-http/oauth/broker-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../../../../src/runtime/mcp-http/oauth/broker-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAC/B,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAkC9D"}
+{"version":3,"file":"broker-routes.d.ts","sourceRoot":"","sources":["../../../../src/runtime/mcp-http/oauth/broker-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAC/B,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CA0C9D"}

package/dist/runtime/mcp-http/oauth/broker-routes.js

@@ -15,9 +15,17 @@ export function buildBrokerRoutes(deps) {
     const callbackPath = deps.callbackPath ?? "/oidc/callback";
     // claude.ai lands here (DCR+PKCE already done against our self-AS); we redirect
     // the human to 39-auth to actually log in.
-    router.get("/authorize", (c) => {
+    router.get("/authorize", async (c) => {
         c.header("Cache-Control", "no-store");
         const claudeai = c.req.query();
+        if (deps.validateClaudeaiAuthorize) {
+            const v = await deps.validateClaudeaiAuthorize(claudeai);
+            if (!v.ok) {
+                // reject BEFORE sending the human to 39-auth — never issue a code to an
+                // unregistered redirect_uri.
+                return c.json({ error: v.error, error_description: v.description }, 400);
+            }
+        }
         const { redirectUrl } = deps.brokerLogin.start(claudeai);
         return c.redirect(redirectUrl, 302);
     });

package/dist/runtime/mcp-http/oauth/broker-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"broker-routes.js","sourceRoot":"","sources":["../../../../src/runtime/mcp-http/oauth/broker-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAmB5B,MAAM,UAAU,iBAAiB,CAAC,IAAsB;IACtD,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,gBAAgB,CAAC;IAE3D,gFAAgF;IAChF,2CAA2C;IAC3C,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;QAC7B,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,EAA4B,CAAC;QACzD,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,+EAA+E;IAC/E,gEAAgE;IAChE,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACnC,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,EAAE,GAAG,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC1D,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAkC,EAAE;gBACxF,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAG,GAAa,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"broker-routes.js","sourceRoot":"","sources":["../../../../src/runtime/mcp-http/oauth/broker-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B5B,MAAM,UAAU,iBAAiB,CAAC,IAAsB;IACtD,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,gBAAgB,CAAC;IAE3D,gFAAgF;IAChF,2CAA2C;IAC3C,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACnC,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,EAA4B,CAAC;QACzD,IAAI,IAAI,CAAC,yBAAyB,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC;YACzD,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBACV,wEAAwE;gBACxE,6BAA6B;gBAC7B,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,+EAA+E;IAC/E,gEAAgE;IAChE,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACnC,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,EAAE,GAAG,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC1D,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAkC,EAAE;gBACxF,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAG,GAAa,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/h2a-cli",
-  "version": "0.48.0",
+  "version": "0.55.0",
   "description": "Unified CLI surface for h2a hosts and MCP-oriented coordination flows.",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,7 @@
     "@hono/mcp": "^0.3.0",
     "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@sentropic/h2a": "^0.48.0",
+    "@sentropic/h2a": "^0.55.0",
     "hono": "^4.12.23"
   },
   "publishConfig": {

package/skills/h2a/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: h2a
-version: 0.46.0
+version: 0.55.0
 description: Coordinate with other CLI agents (Claude Code, Codex, Gemini) via the h2a protocol — open a live session, list peers, exchange messages, drive a signed negotiation. Use when the user wants the current CLI to interact with another agent through a shared workspace.
 ---
 
@@ -55,11 +55,14 @@ Show the current connectivity state. Steps:
 
 List currently-live peer agents.
 
+**Peer resolution rule — always use `h2a_discover_sessions`, never grep the registry:**
+To reach a peer by PURPOSE/role, RESOLVE it via `h2a_discover_sessions` filtering on `scope` (the canonical purpose key) or `name` (case-insensitive substring match on the agent's display name) — e.g. `{ scope: "scope:chat" }` or `{ name: "radar" }`. NEVER grep the registry for a free-text name: instance ids are workspace-derived (`host:slug(workspace):uuid`), so a name grep misses. If several sessions match, list them and let the user pick (or pick the single live one); if none match, the agent has not advertised that scope/name yet.
+
 Steps:
 
-1. Call `h2a_discover_sessions` with `{ scope }` (omit if no argument).
+1. Call `h2a_discover_sessions` with `{ scope }` (omit if no argument); add `{ name: "<substring>" }` when the user asks to find a peer by friendly name.
 2. Filter out the current agent's own session (compare against `h2a_session_open`'s `sessionId` if known).
-3. For each remaining session, print: `instance`, `host`, `interests.scopes` (comma-joined), a relative heartbeat age ("12s ago"), and `sessionId`.
+3. For each remaining session, print: `instance`, `host`, `name` (if set), `interests.scopes` (comma-joined), a relative heartbeat age ("12s ago"), and `sessionId`.
 4. Sort by host then instance.
 5. If empty: say so and suggest the user check that the other CLIs ran `/h2a connect` against the same root.
 
@@ -74,6 +77,7 @@ Steps:
 1. **Resolve the target + check liveness FIRST (`h2a_discover_sessions`).** Pick the addressing form (see "Identity & addressing"):
    - target is a **specific live agent** → use its **full perennial id** `host:slug:uuid12` from discover (NOT the bare `host:label`, which is ambiguous when several agents share a workspace);
    - target is a **role/channel or a known-dormant peer** → use the **channel** form `host:label`.
+   - If the user names a peer by PURPOSE/role, call `h2a_discover_sessions` with `{ scope: "<purpose>" }`. If the user names a peer by FRIENDLY NAME, call `h2a_discover_sessions` with `{ name: "<substring>" }`. NEVER grep the registry for a name: instance ids are workspace-derived (`host:slug(workspace):uuid`) so a text search misses. If several match, list and ask; if none, the agent hasn't advertised that scope/name.
    - If `<peer>` is missing, list discover and ask the user to pick.
 2. If `"<text>"` is missing, prompt the user for the content.
 3. Compose an `H2AEnvelope` JSON:
@@ -93,6 +97,17 @@ Steps:
    }
    ```
 4. Call `h2a_inbox` with `{ action: "put", instance: "<peer>", envelope }`.
+
+   **Conversation threading (optional, lightweight):** To continue an existing back-and-forth as a thread, add two top-level fields to the envelope JSON before putting it:
+   - `"threadId": "<id>"` — reuse the `threadId` from the peer's previous envelope, or mint a fresh one as `thr:<epoch-ms>:<4hex>` to start a new thread.
+   - `"replyTo": "<prev-envelope-id>"` — the `id` of the envelope you are replying to.
+
+   To reconstruct the ordered fil of a thread (for supervision or before opening a formal negotiation):
+   ```sh
+   h2a thread --id <threadId> --instance <self-instance> --root <root>
+   ```
+   This returns the envelopes (from your inbox + outbox) that share that `threadId`, sorted ascending by `createdAt`, deduped. No new store — storage is derived on the fly.
+
 5. **Report honestly per the target's liveness** (h2a writes the inbox unconditionally — it does NOT yet error on a dead target, so YOU must say which it was):
    - target was **live** in discover → *"Delivered to `<peer>` (live) — push fires if subscribed."*
    - target was **NOT live** → *"`<peer>` is dormant — envelope deposited for its wake (no live session; it will only see this once woken)."* Never claim "Delivered" to a dormant/unknown peer.
@@ -178,6 +193,8 @@ There are **two addressable forms**; pick deliberately:
   drop. A perennial agent also reads its own `host:label` alias inbox (dedup), so
   channel messages reach whichever agent adopts that label.
 
+**Resolution rule — discover, never grep:** To reach a peer by PURPOSE/role, filter `h2a_discover_sessions` on `scope` (the canonical purpose key). To reach a peer by FRIENDLY NAME, filter on `name` (case-insensitive substring match on `session.name`). NEVER grep the registry file for a free-text name: instance ids are workspace-derived (`host:slug(workspace):uuid`), so a name grep misses. If several sessions match, list them and pick/ask; if none match, the agent hasn't advertised that scope/name yet.
+
 Consequences to respect:
 - **Addressing is case-insensitive; the label is slugified** (0.40.0+). The handle
   is canonicalized as `lower(host):slugify(label)[:lower(uuid)]`, so `claude:matchID`