@astrasyncai/verification-gateway 2.4.3 → 2.4.5

package/README.md

@@ -494,6 +494,96 @@ Pre-v2.4.2 used the value `pass-through` — renamed in v2.4.2 to disambiguate "
 
 ## Changelog
 
+### v2.4.5 — Round-13 partner integration testing
+
+**⚠️ BREAKING CHANGE — `pdlss_immutable` → `agent_immutable`**
+
+The 409 response from `PUT /api/agents/:id` (post-mint mutation attempt)
+now returns `error: 'agent_immutable'` instead of `error: 'pdlss_immutable'`.
+The scope also widened: round-12 rejected only the subset
+`{ pdlss, model, framework, agentType, apiEndpoint }`; round-13 rejects
+ANY field except `agentStatus` (the only allowed lifecycle transition
+post-mint).
+
+**Migration**: if your code catches `pdlss_immutable`, update to
+`agent_immutable`. No legacy alias is shipped — clean break prevents
+permanent shim cruft. The new shape:
+
+```json
+{
+  "success": false,
+  "error": "agent_immutable",
+  "message": "Agents are immutable post-approval. ... Attempted immutable fields: <list>. ...",
+  "immutableFields": ["name", "description", ...]
+}
+```
+
+**Why**: agents become immutable at approval + mint per the trust-chain
+invariant. Pre-mint owner edits flow through
+`POST /agents/request-registration/:requestId/approve` (dashboard-only,
+accepts a full edit body). Post-mint, the only allowed transition is
+`agentStatus` (e.g. dashboard retire button). For configuration changes,
+use the upgrade flow (coming soon) or retire-and-re-register.
+
+**Other round-13 items**:
+
+- **R13-1 + R13-2 — MCP middleware: symmetric precedence chain for
+  `purpose` and `action`**. Canonical resolution (documented ONCE,
+  applies to both):
+  1. `X-Astra-<concept>` HTTP header
+  2. `params._meta.astrasync.<concept>` body field
+  3. `params.arguments.<concept>` body field
+  4. Transport-layer default:
+     - `purpose` → `'mcp_invoke'`
+     - `action` → `'<method>:<toolName>'` (or `'<method>'` alone)
+
+  Round-12 F19 shipped purpose with `header → _meta → default`; this
+  round closes the `params.arguments.purpose` fallback gap AND ships
+  action with the same full chain in one round (not staggered) to
+  pre-empt the parallel "I set action in arguments and it didn't take"
+  support tickets. Resource string stays `mcp:tool/<name>` regardless.
+
+  `mcpToPdlss(parsed, headerPurpose, headerAction)` signature.
+  `McpPdlssMapping.purposeSource` now `'header' | 'meta' | 'tool_argument' | 'default_mcp_invoke'`
+  (round-12 narrower `'header' | 'tool_argument' | 'default_mcp_invoke'`
+  widened to split `meta` from `tool_argument`). New companion
+  `actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer'`.
+
+- **R13-5 — MCP `evaluateAlwaysIfCredentialed` parity with F9**. Flag
+  moved from `ExpressMiddlewareOptions` to `GatewayConfig` so both
+  adapters inherit. MCP middleware now mirrors the express F9 pattern:
+  route-none + flag-on + credentialed → run verify-access for the audit
+  trail, populate `req.agentVerification`, then proceed without gates
+  (`X-Astra-Gateway-Mode: enforced`, `Reason: evaluated-not-enforced`).
+  Closes the round-12 deferral.
+
+- **F14 closure — `sdkVersion` body field on verify-access**. Replaces
+  round-12's User-Agent regex extraction which silently failed because
+  Node's undici fetch doesn't ship a usable User-Agent header. The SDK
+  now sets `body.sdkVersion = SDK_VERSION` (sourced from
+  `packages/verification-gateway/src/version.ts`, bumped alongside
+  `package.json` on every release). Backend reads from the body field
+  and runs the same forward-only auto-pop into
+  `kya_counterparty.sdk_version`. Works in Node, browser, and behind
+  CDNs uniformly.
+
+- **R13-4 — Branded TypeScript types** (compile-time protection against
+  the recurring UUID / public-id string-confusion bug class —
+  round-7 #46, round-11 F1, round-12 F15). New `CounterpartyUuid`,
+  `AgentUuid`, `OwnerUuid`, `CounterpartyAstraeId`, `AgentAstraId`,
+  `OwnerAstradId` branded types in the backend at
+  `apps/backend/src/types/branded-ids.ts`. Zero runtime cost; affects
+  only compile-time assignment compatibility. Scope intentionally
+  narrow — only the conversion-point function signatures.
+
+### v2.4.4 — Round-12 partner integration testing
+
+- **F9** — `ExpressMiddlewareOptions.evaluateAlwaysIfCredentialed`: when true + credentials present + route-none, the middleware calls verify-access for the audit trail + `req.agentVerification` population, then proceeds without enforcement. Default false preserves existing behaviour. Use for tiered-response rendering on routes that grant public access but want caller identity visible to the handler.
+- **F12** — `defaultOnDenied` / `defaultMcpDenied` synthesise `access_level.insufficient` failure entry on accessLevel-below-route + trust-score-below-route denials. Guidance text references the step-up verification flow ("coming soon — ships this month") only. Prior denials carried `INSUFFICIENT_ACCESS` with empty `failures[]` / `denialReasons[]` arrays.
+- **F16** — `register()` now passes the API response's `warnings[]` through verbatim on both 201 (sync) and 202 (pending-approval) paths. Pre-fix the SDK silently dropped backend advisories like `no_callback_endpoint`. `RegisterResult` + `PendingRegistrationResponse` + `RegistrationResponse` types extended.
+- **F19** — MCP middleware purpose pass-through. The hardcoded `purpose: 'mcp_invoke'` is now a fallback; resolution precedence is `X-Astra-Purpose` header → `params._meta.astrasync.purpose` → `'mcp_invoke'` default. Adds `invocationProtocol: 'mcp'` to the verify-access body so transport is marked separately from intent. Debug-level `purpose_source` log line per call for adoption tracking + support triage.
+- **`mcpToPdlss`** signature extended to accept optional `headerPurpose` + `toolArgumentPurpose` args; return type gains `purposeSource: 'header' | 'tool_argument' | 'default_mcp_invoke'`.
+
 ### v2.4.3 — Round-11 partner integration testing
 
 - **`PollRegistrationResult.astraId`** — the polling response now surfaces the canonical `ASTRA-*` id once the registration request is approved. Pre-fix partners only got the owner-private UUID from the register flow and had no programmatic path to the canonical id (had to go to the dashboard). Backend changes that drive this: the `GET /api/agents/request-registration/{requestId}` handler looks up `kyaAgent.astrasyncIdLevel1` on approval and includes it in the response body.

package/dist/adapter-interface/interface.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-C_e1IZdU.mjs';
-import '../types-DLai3jly.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-tBNFSbw_.mjs';
+import '../types-CbZOkIr-.mjs';
 
 /**
  * PlatformAdapter Interface

package/dist/adapter-interface/interface.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-IUzu-A4u.js';
-import '../types-DLai3jly.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-DXNkr61h.js';
+import '../types-CbZOkIr-.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-DLai3jly.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DneHiMhu.mjs';
+import '../types-CbZOkIr-.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-D5hAJ2Gv.mjs';

package/dist/adapters/express.d.ts

@@ -1,3 +1,3 @@
 import 'express';
-import '../types-DLai3jly.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DsiaQRFt.js';
+import '../types-CbZOkIr-.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-XCkk7BsJ.js';

package/dist/adapters/express.js

@@ -44,6 +44,9 @@ function hasMinimumAccess(actual, required) {
   return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
 }
 
+// src/version.ts
+var SDK_VERSION = "2.4.5";
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -201,6 +204,8 @@ async function callVerifyAccessAPI(config, request) {
   if (config.counterpartyId) body.counterpartyId = config.counterpartyId;
   if (requestData.runtimeChallengeOptions)
     body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
+  if (requestData.invocationProtocol) body.invocationProtocol = requestData.invocationProtocol;
+  body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
     const meta = {
       ...requestData.clientIp && { sourceIp: requestData.clientIp },
@@ -672,14 +677,15 @@ function createMiddleware(options) {
         }
         return next();
       }
-      if (routeConfig.minAccessLevel === "none") {
+      const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
+      const shouldEnforce = routeConfig.minAccessLevel !== "none";
+      if (routeConfig.minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "route-none");
         }
         return next();
       }
-      const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
       const purpose = customExtractPurpose ? customExtractPurpose(req) : defaultExtractPurpose(req);
       const astraCreds = extractAstraSyncCredentials(req);
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}`;
@@ -743,9 +749,27 @@ function createMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (!shouldEnforce) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "enforced");
+          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
+        }
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "granted").catch(() => {
+          });
+        }
+        return next();
+      }
       if (!hasMinimumAccess(result.accessLevel, routeConfig.minAccessLevel)) {
+        const insufficientFailure = {
+          dimension: "access_level.insufficient",
+          message: `Endpoint requires accessLevel '${routeConfig.minAccessLevel}'; agent has '${result.accessLevel}'.`,
+          guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
+        };
+        result.failures = [...result.failures ?? [], insufficientFailure];
+        result.denialReasons = [...result.denialReasons ?? [], insufficientFailure.message];
         if (shouldRecordDecisions && sessionId) {
-          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          recordDecision(config, sessionId, "denied", insufficientFailure.message).catch(() => {
           });
         }
         onDenied(result, req, res);
@@ -753,11 +777,15 @@ function createMiddleware(options) {
       }
       if (routeConfig.minTrustScore && result.agent) {
         if (result.agent.trustScore < routeConfig.minTrustScore) {
-          result.denialReasons = [
-            `Trust score ${result.agent.trustScore} is below required ${routeConfig.minTrustScore}`
-          ];
+          const trustFailure = {
+            dimension: "access_level.insufficient",
+            message: `Trust score ${result.agent.trustScore} is below required ${routeConfig.minTrustScore} for this route.`,
+            guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
+          };
+          result.failures = [...result.failures ?? [], trustFailure];
+          result.denialReasons = [trustFailure.message];
           if (shouldRecordDecisions && sessionId) {
-            recordDecision(config, sessionId, "denied", result.denialReasons[0]).catch(() => {
+            recordDecision(config, sessionId, "denied", trustFailure.message).catch(() => {
             });
           }
           onDenied(result, req, res);