@astrasyncai/verification-gateway 2.4.0 → 2.4.2

package/README.md

@@ -105,35 +105,109 @@ if (result.verified && result.accessLevel !== 'none') {
 
 ### Agent Registration
 
-Register an AI agent with the KYA backend in code (the `astrasync` CLI does the same thing from a shell).
+**Use the SDK for all agent registration**, whether you're a developer firing off a one-shot CLI call or an autonomous agent self-registering on first run. The SDK handles auth-mode routing for you: signature-authenticated callers get synchronous registration; API-key-only callers get an owner-approval handshake (server-side rule, not negotiable).
+
+#### `apiEndpoint` — runtime-challenge URL
+
+`apiEndpoint` is the URL where your agent's verification-gateway SDK is mounted to receive runtime challenges from counterparties. Optional but recommended — if you omit it, your agent declares no runtime-challenge support, which is included in the verification payload and may cause some counterparties to decline access requests.
+
+#### Two registration response modes
+
+The same `register()` call returns one of two shapes depending on auth context:
+
+- **201 active** — synchronous: returned when the request is signed with a crypto keypair (`privateKey` configured) or when authenticated via email+password. Result: `{ status: 'active', agent }`.
+- **202 pending_approval** — API-key only: the SDK was authenticated with an API key but the request was not signed. The backend emails the account owner a "Sign In to Accept" link, fires a dashboard alert, and returns a tracking token. Result: `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The agent becomes active only after the owner approves.
+
+This split enforces the platform rule that **API-key registrations always require owner step-up** — registering an agent autonomously with just an API key is not a sufficient authority signal on its own.
+
+#### Pattern A — developer / long-running agent (block until approved)
+
+Best for CLI tools, dev-machine first-run, and long-running services:
 
 ```typescript
-import { AstraSync } from '@astrasyncai/verification-gateway/registration';
+import {
+  AstraSync,
+  RegistrationDeniedError,
+  RegistrationTimeoutError,
+} from '@astrasyncai/verification-gateway/registration';
 
-const astrasync = new AstraSync({
-  apiKey: process.env.ASTRASYNC_API_KEY, // or { email, password }
-  // Optional: privateKey for secp256k1 request signing
-  privateKey: process.env.ASTRASYNC_PRIVATE_KEY,
+const sdk = new AstraSync({
+  apiKey: process.env.ASTRASYNC_API_KEY,
+  privateKey: process.env.ASTRASYNC_PRIVATE_KEY, // optional — when set, 201 sync path
 });
 
-const result = await astrasync.register({
+try {
+  const agent = await sdk.register({
+    name: 'invoice-bot',
+    description: 'Reconciles AP/AR across accounting systems.',
+    agentType: 'autonomous',
+    apiEndpoint: 'https://invoice-bot.example.com', // runtime-challenge URL
+    model: { modelProvider: 'anthropic', modelName: 'claude-sonnet-4-5' },
+    framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },
+    protocols: ['a2a', 'mcp'],
+    pdlss: {
+      purpose: {
+        categories: ['accounting'],
+        allowedActions: ['accounting.read', 'accounting.write'],
+      },
+      limits: { stepUpThreshold: 1_000, approvalThreshold: 10_000, currency: 'USD' },
+      scope: { resources: ['xero.invoices', 'quickbooks.bills'] },
+      selfInstantiation: { allowed: false },
+    },
+    // Blocking mode: poll until the request resolves.
+    waitForApproval: true,
+    timeoutMs: 10 * 60 * 1000, // 10 minutes default
+    onPending: ({ ageMs }) =>
+      console.log(`Awaiting owner approval (${(ageMs / 1000).toFixed(0)}s)…`),
+  });
+  console.log(`Agent registered: ${agent.astrasyncIdLevel1}`);
+} catch (err) {
+  if (err instanceof RegistrationDeniedError) {
+    console.error('Owner denied:', err.reason);
+  } else if (err instanceof RegistrationTimeoutError) {
+    console.error(
+      'Timed out — request is still active server-side; poll later via sdk.waitForApproval(requestId)'
+    );
+  } else {
+    throw err;
+  }
+}
+```
+
+#### Pattern B — serverless / scheduled agent (non-blocking, exit and resume)
+
+Best for Lambda / Cloud Functions / cron-driven self-registration where you can't hold the runtime open for minutes:
+
+```typescript
+const sdk = new AstraSync({ apiKey: process.env.ASTRASYNC_API_KEY });
+
+const result = await sdk.register({
   name: 'invoice-bot',
-  description: 'Reconciles AP/AR across accounting systems.',
-  agentType: 'autonomous',
-  model: { modelProvider: 'anthropic', modelName: 'claude-sonnet-4-5' },
-  framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },
-  protocols: ['a2a', 'mcp'],
-  pdlss: {
-    purpose: { allowed: ['accounting.read', 'accounting.write'] },
-    duration: { requested: 'P30D' },
-    limits: { transactionValue: 5000, currency: 'USD' },
-    scope: { resources: ['xero.invoices', 'quickbooks.bills'] },
-    selfInstantiation: { allowed: false },
-  },
+  apiEndpoint: 'https://invoice-bot.example.com',
+  pdlss: { purpose: { categories: ['accounting'], allowedActions: ['accounting.read'] } },
 });
 
-console.log(`Agent registered: ${result.agent.astraId}`);
-console.log(`Trust score: ${result.agent.trustScore}`); // dynamic; recomputed on every verify-access call
+if (result.status === 'pending_approval') {
+  // Store the requestId in your durable storage (DynamoDB, KV, etc.)
+  await store.set('astrasync.pendingRequestId', result.requestId);
+  console.log(`Awaiting owner approval at ${result.pollUrl}; will resume on next scheduled run.`);
+  return; // function exits — owner has time to approve
+}
+
+console.log(`Agent registered as ${result.agent.astrasyncIdLevel1}`);
+```
+
+On the next scheduled run, resume by polling:
+
+```typescript
+const requestId = await store.get('astrasync.pendingRequestId');
+const status = await sdk.pollRegistration(requestId);
+if (status.state === 'approved') {
+  await store.set('astrasync.agentId', status.agent.kyaAgentId);
+  await store.delete('astrasync.pendingRequestId');
+} else if (status.state === 'denied' || status.state === 'expired') {
+  console.error(`Registration terminated: ${status.state}`);
+}
 ```
 
 CLI equivalent — same surface from a shell, also via `npx`:
@@ -143,9 +217,12 @@ npx astrasync register --name invoice-bot --agent-type autonomous \
   --model-provider anthropic --model-name claude-sonnet-4-5 \
   --framework-name langchain --framework-version 0.3.0 \
   --protocols a2a,mcp \
-  --pdlss '{"purpose":{"allowed":["accounting.read","accounting.write"]}, ...}'
+  --api-endpoint https://invoice-bot.example.com \
+  --pdlss '{"purpose":{"categories":["accounting"],"allowedActions":["accounting.read"]}}'
 ```
 
+The CLI uses the same response logic — it will print a "Sign in to approve" message and a poll URL when the response is 202 pending, and exit non-zero on deny/expire.
+
 > `/registration` is for **one-shot onboarding** — register an agent, look up its public profile, check API health. For **per-request credential injection** (attaching ASTRA-id, sessionId, PDLSS to outgoing HTTP / A2A / MCP calls from an already-registered agent), use `/agent` (`AgentClient`). The two roles are deliberately separate concerns: registration is identity, `/agent` is runtime.
 
 > A `PDLSSConfig` type exists in both `/registration` and `/agent`, with **different shapes**. `/registration`'s `PDLSSConfig` is the boundary declaration submitted at register time; `/agent`'s `PDLSSConfig` is the per-request runtime request shape. Disambiguate via the import path — the root export deliberately does not re-export either.
@@ -380,6 +457,44 @@ When an unverified agent visits a protected page, the Commerce Shield overlay di
 
 This creates a smooth experience for agents while maintaining security.
 
+## Two `baseUrl` conventions — same package, different clients
+
+This package ships two clients. They use slightly different URL conventions; this is intentional but worth pinning down:
+
+| Client                                                                       | Field                      | Expected value          | Example                    |
+| ---------------------------------------------------------------------------- | -------------------------- | ----------------------- | -------------------------- |
+| Verification gateway (`createMiddleware`, `createMcpMiddleware`, `verify()`) | `GatewayConfig.apiBaseUrl` | Origin + `/api`         | `https://astrasync.ai/api` |
+| Registration SDK (`new AstraSync(...)`)                                      | `AstraSyncConfig.baseUrl`  | Bare origin (no `/api`) | `https://astrasync.ai`     |
+
+Why the split: the gateway derives multiple endpoints from `apiBaseUrl` (verify-access, fetchRoutes, recordDecision, etc.), all under `/api/*`. The registration SDK prepends `/api/agents/...` per call and would double the path if `baseUrl` already ended with `/api`.
+
+As of **v2.4.2**, the registration SDK tolerates a trailing `/api` on `baseUrl` — it strips the suffix and emits a one-time console warning so you can fix the source. Pass `silent: true` in `AstraSyncConfig` to suppress the warning (e.g. in tests).
+
+## Header semantics — `X-Astra-Gateway-Mode`
+
+The SDK sets `X-Astra-Gateway-Mode` on every response that's been through the gateway middleware. The value describes the GATE state — not whether the request succeeded end-to-end.
+
+| Value        | Meaning                                                                                                                                                                                                                                    |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enforced`   | The gateway evaluated policy on this request. Set on denial responses (`defaultOnDenied`, `defaultMcpDenied`).                                                                                                                             |
+| `unenforced` | The gateway skipped policy evaluation for this request. The `X-Astra-Gateway-Reason` header explains why (`mcp-tier-none`, `non-jsonrpc-body`, `no-policy`, `no-match`, `route-none`). The downstream handler may still return any status. |
+
+Pre-v2.4.2 used the value `pass-through` — renamed in v2.4.2 to disambiguate "gate skipped" from "request allowed".
+
+## Changelog
+
+### v2.4.2 — Round-10 partner re-test alignment
+
+- **baseUrl normalization** (`AstraSyncConfig`): trailing `/api` is stripped + warned. Removes a class of NOT_FOUND bugs when partners pass the verify-gateway-style URL to the registration client.
+- **Denial responses surface `failures[]` + `correlationId`** (`defaultOnDenied`, `defaultMcpDenied`): partners can now render per-dimension UX and tie a denial back to a server log line. Previously only the first denialReason was surfaced.
+- **API-error fallback** (`createGuidanceResponse`): synthesised stubs for transient 5xx / network failures now carry `verify_access.api_error` in `failures[]` instead of the misleading "register your agent" template.
+- **`X-Astra-Gateway-Mode` rename**: `pass-through` → `unenforced`. The new `enforced` value lands on denial paths. See the header semantics table above.
+- **`silent` config flag** (`AstraSyncConfig`): suppresses one-time SDK warnings (baseUrl strip, deprecation notices).
+
+### v2.4.1 — Round-9 docs/SDK alignment
+
+See git log for details.
+
 ## License
 
 MIT

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-pU2O0BFq.mjs';
-import '../types-BVp22KkN.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-C_e1IZdU.mjs';
+import '../types-DLai3jly.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-DVCWReEN.js';
-import '../types-BVp22KkN.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-IUzu-A4u.js';
+import '../types-DLai3jly.js';
 
 /**
  * PlatformAdapter Interface

package/dist/adapters/express.d.mts

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

package/dist/adapters/express.d.ts

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

package/dist/adapters/express.js

@@ -130,8 +130,18 @@ function extractCredentials(headers, query) {
   }
   return credentials;
 }
-function createGuidanceResponse(config, reason) {
-  const guidance = {
+function createGuidanceResponse(config, reason, options = {}) {
+  const source = options.source ?? "no_credentials";
+  const isApiError = source === "api_error";
+  const guidance = isApiError ? {
+    message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
+    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
+    documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
+    steps: [
+      "Retry the request with exponential backoff",
+      "If failures persist, share the correlationId with support"
+    ]
+  } : {
     message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
     registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
     documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
@@ -152,6 +162,18 @@ function createGuidanceResponse(config, reason) {
     accessLevel: "none",
     guidance,
     denialReasons: reason ? [reason] : ["No valid agent credentials provided"],
+    // Round-10 (#47, O5): on API-error fallback, surface a typed failure so
+    // partners (and their custom onDenied handlers) can branch on
+    // dimension. Without this, the synthesised stub was indistinguishable
+    // from a real policy deny.
+    failures: isApiError ? [
+      {
+        dimension: "verify_access.api_error",
+        message: reason ?? "Verification temporarily unavailable",
+        guidance: guidance.message
+      }
+    ] : void 0,
+    correlationId: options.correlationId,
     verifiedAt: /* @__PURE__ */ new Date()
   };
 }
@@ -226,7 +248,8 @@ async function callVerifyAccessAPI(config, request) {
     if (!response.ok) {
       return {
         success: false,
-        error: data.message || data.error || `API returned ${response.status}`
+        error: data.message || data.error || `API returned ${response.status}`,
+        correlationId: typeof data?.correlationId === "string" ? data.correlationId : void 0
       };
     }
     return data;
@@ -270,7 +293,10 @@ async function verify(config, request) {
   }
   const apiResponse = await callVerifyAccessAPI(mergedConfig, enrichedRequest);
   if (!apiResponse.success) {
-    return createGuidanceResponse(mergedConfig, apiResponse.error);
+    return createGuidanceResponse(mergedConfig, apiResponse.error, {
+      source: "api_error",
+      correlationId: apiResponse.correlationId
+    });
   }
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
@@ -563,13 +589,17 @@ function findRouteConfig(routes, path, method) {
 }
 function defaultOnDenied(result, _req, res) {
   const statusCode = result.verified ? 403 : 401;
+  res.setHeader("X-Astra-Gateway-Mode", "enforced");
   res.status(statusCode).json({
     success: false,
     error: {
       code: result.verified ? "INSUFFICIENT_ACCESS" : "UNAUTHORIZED",
       message: result.denialReasons?.[0] || "Access denied",
       accessLevel: result.accessLevel,
-      guidance: result.guidance
+      guidance: result.guidance,
+      // Round-10: aggregated per-dimension detail + correlation handle.
+      failures: result.failures,
+      correlationId: result.correlationId
     }
   });
 }
@@ -634,7 +664,7 @@ function createMiddleware(options) {
       const routeConfig = findRouteConfig(cachedRoutes, req.path, req.method);
       if (!routeConfig) {
         if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "pass-through");
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader(
             "X-Astra-Gateway-Reason",
             cachedRoutes.length === 0 ? "no-policy" : "no-match"
@@ -644,7 +674,7 @@ function createMiddleware(options) {
       }
       if (routeConfig.minAccessLevel === "none") {
         if (config.setPassThroughHeader) {
-          res.setHeader("X-Astra-Gateway-Mode", "pass-through");
+          res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "route-none");
         }
         return next();