@aventara/mcp 1.0.0-rc.1 → 1.0.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @aventara/mcp
 
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- 9366e16: MCP endpoint polish:
+
+  - A request with no bearer credentials (no `Authorization` header, or another scheme such as `Basic`) is answered
+    `401` with `WWW-Authenticate: Bearer resource_metadata="…"` and no error code, as RFC 6750 §3.1 asks; its body no
+    longer says "Missing Authorization header". A bad bearer token keeps `error="invalid_token"`.
+  - A `mcp.authorization.verify` that throws is still answered `401`, and is now reported to the `diagnostics` sink as
+    an `AvMcpDiagnostic` holding the error.
+  - With `mcp` configured and `@aventara/mcp` missing, the startup error names the command that installs it at the
+    installed `@aventara/core`'s exact version: `npm install --save-exact @aventara/mcp@<version>`.
+
+- A tool call whose `resource` or `variant` holds a lone surrogate (JSON can carry one, a URL cannot) is answered as
+  the unknown name it is, as an HTTP call answers it: `fetch` spells a lone surrogate in a URL as U+FFFD, and so does
+  the tool call, so the agent gets `A2001` (`A2002` for the variant). In rc.1 the name could not be encoded, and the
+  call answered the generic `A3000` and reported a diagnostic of kind `mcp`. A `transaction` step that has no canonical
+  form (a lone surrogate in a name or a value) is sent with a `null` fingerprint, as core's plan builders and the
+  generated client send it, so it is judged as over HTTP: an unknown name is `A2001`/`A2002`, a value `A2004` `V1001`
+  at the step's `args`. It answered `V1000` for a missing `fingerprint`, a member the tool does not take.
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+  - @aventara/core@1.0.0-rc.2
+
 ## 1.0.0-rc.1
 
 ### Minor Changes

package/README.md

@@ -10,7 +10,7 @@ over the Streamable HTTP transport, stateless. You install this package beside `
 yourself.
 
 ```bash
-npm install @aventara/mcp@rc
+npm install --save-exact @aventara/mcp@<your @aventara/core version>
 ```
 
 It depends on `@aventara/core` and the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`).
@@ -109,9 +109,12 @@ mcp: {
 
 - `GET /.well-known/oauth-protected-resource/mcp` answers the protected-resource metadata (RFC 9728): the endpoint's
   URL as `resource`, your `servers` as `authorization_servers`, and `bearer_methods_supported: ["header"]`.
-- A request without `Authorization: Bearer <token>` is `401` with a `WWW-Authenticate` header naming that metadata,
-  which is how an MCP client discovers where to sign in.
-- Each token goes to `verify`. `null` (or `undefined`, or a throw) is `401`. Anything else lets the request in, and
+- A request without `Authorization: Bearer <token>` is `401` with `WWW-Authenticate: Bearer resource_metadata="…"`
+  naming that metadata, which is how an MCP client discovers where to sign in. As RFC 6750 asks, it carries no error
+  code: the request had no token to be wrong.
+- Each token goes to `verify`. `null` (or `undefined`, or a throw) is `401` with `error="invalid_token"`. A `verify`
+  that throws is also reported to your `diagnostics` sink (an `AvMcpDiagnostic` holding the error), so an outage of
+  your token check shows in your logs rather than as a run of rejected agents. Anything else lets the request in, and
   what `verify` returned is the request's `ctx.$state.mcp.claims`, beside what the host's `state` option seeds. Declare
   its type with the rest of your state:
 

package/dist/endpoint-access.policy.d.ts

@@ -24,10 +24,11 @@ export declare function jsonAnswer(status: number, body: unknown, headers?: Read
  */
 export declare function metadataAnswer(method: string, origin: string, endpointPath: string, authorization: EndpointAuthorization): AvProtocolResponse;
 /**
- * A protected endpoint's check: the request's bearer token, verified. A missing
+ * A protected endpoint's check: the request's bearer token, verified. No bearer
  * token, one `verify` rejects (`null`, `undefined`) and a `verify` that throws
- * are each `401`; a good one passes with what `verify` resolved it to.
+ * are each `401`; a good one passes with what `verify` resolved it to. A throw
+ * is handed to `reportFailure` (the diagnostics sink) as well.
  */
-export declare function authorizedAccess(authorizationHeader: string | undefined, origin: string, endpointPath: string, authorization: EndpointAuthorization): Promise<EndpointAccess>;
+export declare function authorizedAccess(authorizationHeader: string | undefined, origin: string, endpointPath: string, authorization: EndpointAuthorization, reportFailure: (error: unknown) => void): Promise<EndpointAccess>;
 /** An open endpoint's check: the caller is on this machine. */
 export declare function loopbackAccess(remoteAddress: string | undefined, header: (name: string) => string | undefined): EndpointAccess;

package/dist/endpoint-access.policy.js

@@ -23,31 +23,37 @@ function bearerTokenOf(header) {
     const match = /^Bearer[ \t]+([^ \t].*?)[ \t]*$/i.exec(header ?? "");
     return match?.[1];
 }
-function challenge(origin, endpointPath, description) {
-    const metadata = `${origin}${metadataPathOf(endpointPath)}`;
-    return jsonAnswer(401, { error: "invalid_token", error_description: description }, {
-        "WWW-Authenticate": `Bearer error="invalid_token", error_description="${description}", resource_metadata="${metadata}"`,
+function challenge(origin, endpointPath, invalid) {
+    const metadata = `resource_metadata="${origin}${metadataPathOf(endpointPath)}"`;
+    if (invalid === undefined) {
+        return jsonAnswer(401, {
+            error: "unauthorized",
+            error_description: "This MCP endpoint requires a bearer token in the Authorization header.",
+        }, { "WWW-Authenticate": `Bearer ${metadata}` });
+    }
+    return jsonAnswer(401, { error: "invalid_token", error_description: invalid.description }, {
+        "WWW-Authenticate": `Bearer error="invalid_token", error_description="${invalid.description}", ${metadata}`,
     });
 }
-export async function authorizedAccess(authorizationHeader, origin, endpointPath, authorization) {
+export async function authorizedAccess(authorizationHeader, origin, endpointPath, authorization, reportFailure) {
     const token = bearerTokenOf(authorizationHeader);
     if (token === undefined) {
-        return {
-            ok: false,
-            response: challenge(origin, endpointPath, "Missing Authorization header"),
-        };
+        return { ok: false, response: challenge(origin, endpointPath) };
     }
     let claims;
     try {
         claims = await authorization.verify(token);
     }
-    catch {
+    catch (error) {
+        reportFailure(error);
         claims = null;
     }
     if (claims === null || claims === undefined) {
         return {
             ok: false,
-            response: challenge(origin, endpointPath, "The access token is invalid"),
+            response: challenge(origin, endpointPath, {
+                description: "The access token is invalid",
+            }),
         };
     }
     return { ok: true, caller: { claims } };

package/dist/mcp.binder.d.ts

@@ -51,7 +51,8 @@ export type AvMcpBinding = {
      * then the MCP message answered as JSON, statelessly. A tool call runs as an
      * agent-origin protocol request. Never rejects: a failure of its own (the MCP
      * SDK's) is answered `500` with no detail and reported to the Framework's
-     * diagnostics sink as an `AvMcpDiagnostic`.
+     * diagnostics sink as an `AvMcpDiagnostic`; a `verify` that throws is
+     * answered `401` and reported the same way.
      */
     readonly handleEndpoint: (request: AvMcpRequest, options?: {
         /**

package/dist/mcp.binder.js

@@ -105,7 +105,7 @@ async function answerEndpoint(bound, request, state) {
         const { authorization } = bound.endpoint;
         const access = authorization === undefined
             ? loopbackAccess(request.remoteAddress, header)
-            : await authorizedAccess(header("authorization"), url.origin, bound.endpoint.path, authorization);
+            : await authorizedAccess(header("authorization"), url.origin, bound.endpoint.path, authorization, bound.reportFailure);
         if (!access.ok) {
             return access.response;
         }

package/dist/tool-call.translator.js

@@ -32,6 +32,9 @@ function protocolRequest(path, body, headers) {
         body: { kind: "raw", content: jsonTextOf(body) },
     };
 }
+function routeSegmentOf(name) {
+    return encodeURIComponent(name.replace(/\p{Surrogate}/gu, "\uFFFD"));
+}
 export function translateOperationCall(family, input, received, identity) {
     if (!isRecord(input)) {
         return {
@@ -46,7 +49,7 @@ export function translateOperationCall(family, input, received, identity) {
             message: `${family}: \`resource\` and \`variant\` must be strings (read ${CONTRACT_RESOURCE_URI}).`,
         };
     }
-    const path = `/_resources/${[resource, family, variant].map(encodeURIComponent).join("/")}`;
+    const path = `/_resources/${[resource, family, variant].map(routeSegmentOf).join("/")}`;
     return {
         ok: true,
         kind: "operation",
@@ -80,8 +83,8 @@ export async function translateTransactionCall(input, received, identity) {
             args,
         };
         const fingerprint = await fingerprintOf(node);
-        fingerprints.push(fingerprint ?? "");
-        operations.push(fingerprint === undefined ? node : { ...node, fingerprint });
+        fingerprints.push(fingerprint);
+        operations.push({ ...node, fingerprint });
     }
     return {
         ok: true,
@@ -94,7 +97,7 @@ async function fingerprintOf(node) {
         return await computeOperationFingerprint(node);
     }
     catch {
-        return undefined;
+        return null;
     }
 }
 function referenced(value, fingerprints) {
@@ -163,7 +166,7 @@ function withFingerprint(value, fingerprints) {
     const fingerprint = typeof operation === "number" && Number.isInteger(operation)
         ? fingerprints[operation]
         : undefined;
-    return fingerprint === undefined || fingerprint === ""
+    return fingerprint === undefined || fingerprint === null
         ? value
         : { $ref: { ...reference, fingerprint } };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/mcp",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The MCP server for an Aventara application: its agent layer as Model Context Protocol tools.",
   "type": "module",
@@ -22,7 +22,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.1",
+    "@aventara/core": "1.0.0-rc.2",
     "@modelcontextprotocol/sdk": "1.30.1",
     "zod": "^4.6.5"
   },
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "1.0.0-rc.1"
+    "@aventara/testing": "1.0.0-rc.2"
   },
   "scripts": {
     "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",