@astrasyncai/verification-gateway 2.4.4 → 2.4.6

package/README.md

@@ -494,6 +494,166 @@ Pre-v2.4.2 used the value `pass-through` — renamed in v2.4.2 to disambiguate "
 
 ## Changelog
 
+### v2.4.6 — Round-14 partner integration testing
+
+**⚠️ BREAKING CHANGE — `endpointUrl` → `counterpartyUrl` on `POST /api/endpoints` AND `PUT /api/endpoints/{id}`**
+
+The body field renamed to align with every other surface (verify-access,
+dashboard policy, SDK config — all use `counterparty*`). Applies to BOTH
+create (POST) and update (PUT) verbs:
+
+- `POST /api/endpoints` — request body uses `counterpartyUrl` (was `endpointUrl`).
+- `PUT /api/endpoints/{id}` — same. The strict-mode validator on both
+  verbs returns a clean 400 `unrecognized_keys` naming `counterpartyUrl`
+  as the expected key when partners send the old field name.
+- Response shape (`GET /api/endpoints/{id}`) also renamed for full symmetry —
+  partners receive `counterpartyUrl` on read AND send `counterpartyUrl`
+  on write. DB column `endpoint_url` stays as the internal join key; the
+  service layer maps the public name to the DB column.
+
+**Migration**: if your code posts `endpointUrl` to `POST /api/endpoints`
+OR `PUT /api/endpoints/{id}`, rename to `counterpartyUrl`. If your code
+reads `.endpointUrl` from GET responses, rename to `.counterpartyUrl`.
+No legacy alias is shipped — clean break per the
+`feedback_hard_break_no_legacy_shim` discipline.
+
+**Other round-14 items**:
+
+- **Item 1 — F8 runtime-challenge gate moved from SEND to RECOMMENDATION**
+  (`agents.routes.ts`). Round-12 placed the gate at the SEND
+  (`if (data.enableRuntimeChallenge && counterparty.requiresRuntimeChallenge)`)
+  which suppressed the challenge entirely on F8=optional, losing the
+  trust-scoring data the result feeds. Round-14 moves the gate to the
+  recommendation outcome:
+  - challenge ALWAYS fires when `enableRuntimeChallenge: true` (captures
+    trust-scoring data for every call; the result lands on the response
+    body's `runtimeChallenge` block regardless of F8 setting)
+  - failure / timeout only escalates `recommendation` (→ `deny` /
+    `step_up_required`) when the endpoint declared
+    `requiresRuntimeChallenge: true`
+
+  Extracted into a pure helper `deriveRuntimeChallengeRecommendation` so
+  the 6-quadrant truth table is unit-testable without the full verify-access
+  stack. See `/docs/agent-access/runtime-challenge` for the partner-facing
+  contract page (new in this round).
+
+- **New `/docs/agent-access/runtime-challenge` page** documenting the
+  agent-side challenge contract — request shape, response shape, HTTP
+  status semantics, signing posture (unsigned v1; DPoP RFC 9449 on the
+  roadmap as the cryptographic upgrade path), timing, replay semantics.
+  Headlines the `ChallengeHandler` drop-in from
+  `@astrasyncai/verification-gateway/agent`; curl is the wire-spec
+  fallback.
+
+- **New `/docs/mcp-integration` "Purpose + action precedence" section**
+  documenting the 4-tier chain (`header → _meta → arguments → default`)
+  that applies to both purpose and action. Closes the round-13 SDK-README-
+  only documentation gap.
+
+- **`/docs/agent-access` revisions**: section 4b expanded to a dedicated
+  "Headers an integrating agent must send" section covering `X-Astra-Id`,
+  `X-Astra-Purpose`, `X-Astra-Action` (the last is new partner-facing
+  documentation for the round-13 R13-2 header). Section 5 inverted
+  `tokenGuidance` text corrected. New section 5b "What verify-access
+  tells you" annotates the full grant payload with cross-links to the
+  SDK's exported TypeScript types (`VerificationResult`, `TokenGuidance`,
+  `EnhancedVerificationResult`).
+
+- **`/docs/merchants` additions**: worked endpoint POST + PUT examples
+  using the new `counterpartyUrl` name; per-protocol terminal-status
+  table with explicit external-contract preamble (the literals come
+  from each protocol's published spec, not from AstraSync's choice) +
+  auth/capture two-step callout for agent-pay and TAP; A2A JSON-RPC
+  worked example.
+
+- **F14 Health Check tooltip reframed** as descriptive-only metadata
+  ("active probe on roadmap") — the storage + serializer + dashboard UI
+  exist but the active probe pipeline isn't implemented yet (deferred to
+  a focused future round). Sets partner expectations correctly while the
+  pipeline lands.
+
+### 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.

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-y13mmzbA.mjs';
-import '../types-CVT-sorC.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-CLP_TDu5.js';
-import '../types-CVT-sorC.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-CVT-sorC.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-Ck2RHZLT.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-CVT-sorC.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-DZmEzCgo.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.6";
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -202,6 +205,7 @@ async function callVerifyAccessAPI(config, request) {
   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 },