@astrasyncai/verification-gateway 5.17.0 → 5.17.1

package/README.md

@@ -112,7 +112,10 @@ if (result.identityVerified && result.policyAllowed) {
 
 #### `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.
+`apiEndpoint` is the base URL where your agent's own `ChallengeHandler` is mounted (AstraSync POSTs to `{apiEndpoint}/astrasync/challenge`). Endpoints can require the runtime challenge endpoint-wide or per route; an agent that can't answer it is denied there.
+
+- **Your own handler:** mount `ChallengeHandler.expressMiddleware()` at `/astrasync/challenge` and set `apiEndpoint`. Since 5.16.0 the handler answers only for counterparties registered for the call in flight — pass `challengeHandler` to `AgentClient` and each `fetch()` registers its destination, or wrap your own calls in `registerPending()` / `removePending()`.
+- **Through a Workforce Guard checkpoint:** leave `apiEndpoint` blank. The checkpoint answers the challenge for every call made through it (it marks those calls `x-astra-via-checkpoint`). A direct call that bypasses the checkpoint is challenged at the checkpoint, which has nothing pending for it, so it fails — unless the agent also has its own handler, which direct calls ring instead.
 
 #### Two registration response modes
 
@@ -385,18 +388,25 @@ import {
 <GuidanceCard guidance={verificationResult.guidance} />
 ```
 
-## Credential Extraction
+## What the middleware reads from a request
 
-Agents can provide credentials via:
+The middleware reads the calling agent's **identity** and passes it to
+verify-access, which your server calls with **your own** API key:
 
 1. **Headers** (recommended):
-   - `X-Astra-Id`: Agent ASTRA-ID
-   - `X-Api-Key`: API key
-   - `Authorization: Bearer <jwt>`: JWT token
-
-2. **Query Parameters** (fallback):
-   - `?astraId=ASTRA-xxx`
-   - `?apiKey=xxx`
+   - `X-Astra-Id`: the agent's ASTRA-ID. It says which agent is calling; it is
+     an identifier, **never a credential**. Anyone can send any agent's id, so
+     protect sensitive routes with PDLSS policy, `allowedOwners`, and the
+     runtime challenge (which only the real agent's handler, or its Workforce
+     Guard checkpoint, can answer).
+   - `X-Api-Key` / `Authorization: Bearer …`: forwarded as observed metadata.
+2. **Query parameters** (fallback): `?astraId=ASTRA-xxx`, `?apiKey=xxx`.
+
+Calling the AstraSync API itself is different: only an API key or a full
+dashboard session token authenticates. A request that offers only
+`X-Astra-Id` is refused with `401 agent_identity_not_a_credential`, and
+first-step sign-in tokens (before the second factor), refresh tokens and
+passkey elevation tokens are refused with 401.
 
 ## Verification Response
 
@@ -466,7 +476,22 @@ if (!decision.authorized) {
 
 ## Step-Up Approval
 
-When a transaction value is between the agent's Autonomous Limit and Hard Limit, verify-access returns `stepUpApproval` on the result:
+The agent's owner can ask to approve requests ("Ask me") on **any** PDLSS
+dimension, not just spend. verify-access then returns
+`recommendation: 'step_up_required'` with `stepUpApproval` and a `failures[]`
+entry naming the dimension. This is **not** a deny: hold the request and poll.
+
+| Dimension          | When                                                      | `failures[].dimension`                      |
+| ------------------ | --------------------------------------------------------- | ------------------------------------------- |
+| Limits             | value above the Autonomous Limit and below the Hard Limit | `commerce.intent.approval_required`         |
+| Purpose            | the action is on the owner's approval list                | `pdlss.purpose.approval_required`           |
+| Duration           | outside the agent's time window, set to ask               | `pdlss.duration.approval_required`          |
+| Scope              | a resource, counterparty or jurisdiction set to ask       | `pdlss.scope.approval_required`             |
+| Self-instantiation | spawning a sub-agent, set to ask                          | `pdlss.selfInstantiation.approval_required` |
+
+The entry names the dimension, never the rule. Once the owner approves, the
+same request (same `attemptId`) passes once. Gate on `recommendation` (or
+`stepUpApproval`), never on a non-empty `failures[]` alone.
 
 ```typescript
 interface StepUpApprovalInfo {
@@ -514,6 +539,26 @@ outlive that budget — behind the bridge, either:
 Either way the attempt chain above guarantees the post-approval re-drive
 passes without a second approval.
 
+### Routes that hold their own approval (v5.17.1)
+
+If a route asks the owner for approval itself — it creates its own hold and
+answers `202` while it waits — set `approvalHeldByRoute` so the owner isn't
+asked twice:
+
+```ts
+createMiddleware({
+  // …
+  approvalHeldByRoute: (req) => req.method === 'POST' && req.path === '/signin',
+});
+```
+
+For matching requests, a result that only needs the owner's approval reaches
+your handler (`req.agentVerification.requiresStepUp` is true and `failures`
+names each `pdlss.<dimension>.approval_required` or
+`commerce.intent.approval_required`); verify-access creates no approval. Your
+route must then hold the request until the owner approves. Any deny is still
+refused.
+
 ## Checkout & settlement (astra-pay)
 
 The first-party commerce rail: an agent shops under its ASTRA-id, holds NO
@@ -823,18 +868,38 @@ The installer registers the `astrasync-claude-hook` binary in Claude Code's `set
 - **MCP governance** — set `"governMcp": true` to govern MCP tools too; `mcp__{server}__{tool}` maps to purpose `{server}.{tool}` in the policy.
 - **Uninstall** — `astrasync-guard uninstall-claude-code` removes the hook; policy and traces are left in place.
 
+## Fleet & Workforce Guard CLI
+
+Organisation-managed commands (Enterprise Governance → Fleet). Run them as
+`astrasync guard <command>`.
+
+| Command            | What it does                                                                                                                                                                                                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enroll <token>`   | Enrol this machine in your organisation's fleet. User scope by default; `--system` enrols the whole machine (needs administrator rights; machine scope wins over user scope). `--api-base-url <url>` targets another environment.                                                   |
+| `fleet-status`     | Show the enrolment, the signed policy and the last heartbeat.                                                                                                                                                                                                                       |
+| `managed-settings` | Print MDM templates for Claude Code and/or Codex (`--claude`, `--codex`, `--out <dir>` to write files). Machines must also be enrolled with `enroll <token> --system`.                                                                                                              |
+| `git-route`        | Route this machine's `git fetch` / `git push` to github.com through your Workforce Guard checkpoint (`--checkpoint <url> --slug <connector> --agent <ASTRA-id>`, `--upstream` default `github`; `--undo` removes it). `git commit` and local hooks are unchanged.                   |
+| `git-credential`   | The git credential helper `git-route` installs. Answers with the agent's ASTRA-id and this machine's device credential; no git host token is stored on the machine. Not run by hand.                                                                                                |
+| `browse`           | Sign an agent in to its owner's dashboard from this machine and run its device proxy (`--checkpoint <url> --slug <agent>`, `--upstream` default `astrasync-api`, `--port`, `--host`). Needs an enrolled machine and `dashboard.signin` in the agent's policy. See CHANGELOG 5.17.0. |
+
+Calls an agent makes through its checkpoint have their runtime challenge
+answered by the checkpoint; the agent needs no `apiEndpoint` of its own.
+
 ## Changelog
 
-### v4.1.0 — Trusted Agent Gateway naming + MCP metadata capture
+Newest first. Full detail for every release is in [CHANGELOG.md](./CHANGELOG.md).
 
-- The Next.js unverified-agent overlay is now the **verification interstitial**: `showInterstitial` option, `VerificationInterstitial` / `useVerificationInterstitial` / `VerificationInterstitialProps`. The old `showCommerceShield` / `CommerceShield` / `useCommerceShield` / `CommerceShieldProps` names keep working as deprecated aliases until the next major (`showInterstitial` wins when both options are set).
-- The MCP middleware now captures header-level `ObservedMetadata` on every verify-access call (parity with the express/nextjs adapters).
-- The edge product is the **Trusted Agent Gateway (TAG)** — see the new README sections above.
+### v5.17.1 — one approval for a route that holds its own
 
-### v3.8.0 — Settlement voucher wire format v2
+- `approvalHeldByRoute` (Express): a route that holds its own owner approval receives an approval-only result instead of a refusal, and verify-access creates no approval — the owner approves once.
+- A hold on purpose, duration, scope or sub-agents is no longer described as a spending limit; step-up results carry the server's `failures`.
+- `astrasync guard browse` says why a sign-in was refused, and stops at once on a refused status check.
 
-- **BREAKING type change:** `SettlementArtifact.binding` is now a union — `StablecoinSettlementBinding` (v2: `amountMinor` integer minor units + `assetDecimals`, pinned `chainId`/`tokenContract`/CAIP-19 `asset`) or `FiatSettlementBinding` (processor artifacts keep major-unit `amount`). The float `amount` field is gone from stablecoin bindings. Matches the server's `ver: 2` wire format, which redeems/verifies reject other versions of.
-- Settlement Artifacts docs rewritten: voucher lifecycle endpoints (verify / redeem / JWKS), expected-value gates on redeem, revocation semantics, and an explicit **guarantee boundary** — what a successful redeem proves and what it doesn't (redeem proves the authorization is live and single-use; it does not check or move funds).
+### v5.17.0 — `astrasync guard browse`
+
+- `astrasync guard browse` signs an agent in to its owner's dashboard through its
+  Workforce Guard checkpoint, bound to this machine's device credential, and runs
+  the local device proxy its automation browser uses.
 
 ### v5.16.0 — ChallengeHandler auto-include removed
 
@@ -844,6 +909,17 @@ The installer registers the `astrasync-claude-hook` binary in Claude Code's `set
   registers each call while it is in flight; otherwise call
   `registerPending()` / `removePending()` around each interaction.
 
+### v4.1.0 — Trusted Agent Gateway naming + MCP metadata capture
+
+- The Next.js unverified-agent overlay is now the **verification interstitial**: `showInterstitial` option, `VerificationInterstitial` / `useVerificationInterstitial` / `VerificationInterstitialProps`. The old `showCommerceShield` / `CommerceShield` / `useCommerceShield` / `CommerceShieldProps` names keep working as deprecated aliases until the next major (`showInterstitial` wins when both options are set).
+- The MCP middleware now captures header-level `ObservedMetadata` on every verify-access call (parity with the express/nextjs adapters).
+- The edge product is the **Trusted Agent Gateway (TAG)** — see the new README sections above.
+
+### v3.8.0 — Settlement voucher wire format v2
+
+- **BREAKING type change:** `SettlementArtifact.binding` is now a union — `StablecoinSettlementBinding` (v2: `amountMinor` integer minor units + `assetDecimals`, pinned `chainId`/`tokenContract`/CAIP-19 `asset`) or `FiatSettlementBinding` (processor artifacts keep major-unit `amount`). The float `amount` field is gone from stablecoin bindings. Matches the server's `ver: 2` wire format, which redeems/verifies reject other versions of.
+- Settlement Artifacts docs rewritten: voucher lifecycle endpoints (verify / redeem / JWKS), expected-value gates on redeem, revocation semantics, and an explicit **guarantee boundary** — what a successful redeem proves and what it doesn't (redeem proves the authorization is live and single-use; it does not check or move funds).
+
 ### v3.7.1 — ChallengeHandler auto-include (removed in 5.16.0)
 
 - `ChallengeHandler` auto-includes the incoming `counterpartyId`/`counterpartyUrl` in the challenge response when no counterparties were pre-registered via `registerPending()` — the correct default for agents that never call it. Pre-registered whitelists behave exactly as before.

package/dist/adapters/express.d.mts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-Blz520bR.mjs';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-DRb_plOh.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-Blz520bR.js';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-DRb_plOh.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.js

@@ -469,7 +469,7 @@ function routePolicyOf(route) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.17.0";
+var SDK_VERSION = "5.17.1";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -771,6 +771,7 @@ function getCacheKey(request, counterpartyId) {
     request.enableRuntimeChallenge ? "1" : "0",
     // 5.16.0: route policy changes the verdict (owners / challenge).
     request.routePolicy ? JSON.stringify(request.routePolicy) : "",
+    request.approvalHeldByRoute ? "1" : "0",
     // callerMetadata fields contribute to risk model; include the ones
     // backend reads. sourceIp/userAgent/forwardedFor change per-request
     // so their inclusion effectively forces a re-check for any varying
@@ -978,6 +979,7 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.enableRuntimeChallenge)
     body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
   if (requestData.routePolicy) body.routePolicy = requestData.routePolicy;
+  if (requestData.approvalHeldByRoute) body.approvalHeldByRoute = true;
   if (requestData.createSession) body.createSession = requestData.createSession;
   if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
   if (requestData.counterpartyType) body.counterpartyType = requestData.counterpartyType;
@@ -1309,6 +1311,8 @@ async function verify(config, request, options) {
   } else if (result.recommendation === "step_up_required" && result.identityVerified) {
     result.requiresStepUp = true;
     result.denialReasons = serverDenialReasons ?? result.recommendationReasons ?? ["Step-up verification required"];
+    const stepUpFailures = apiResponse.access?.failures;
+    if (stepUpFailures?.length) result.failures = stepUpFailures;
   }
   const escalates = result.requiresStepUp === true || result.requiresApproval === true || result.recommendation === "step_up_required";
   if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny" && !escalates) {
@@ -1543,12 +1547,31 @@ function requiresHumanApproval(result) {
   return result.requiresStepUp === true || result.requiresApproval === true;
 }
 function annotateApprovalRequired(result) {
-  result.failures = [
-    ...result.failures ?? [],
-    { dimension: "commerce.intent.approval_required", message: APPROVAL_REASON }
-  ];
+  if (isDimensionApproval(result)) {
+    result.denialReasons = [DIMENSION_APPROVAL_REASON, ...result.denialReasons ?? []];
+    return;
+  }
+  const named = (result.failures ?? []).some(
+    (f) => f.dimension === "commerce.intent.approval_required"
+  );
+  if (!named) {
+    result.failures = [
+      ...result.failures ?? [],
+      { dimension: "commerce.intent.approval_required", message: APPROVAL_REASON }
+    ];
+  }
   result.denialReasons = [APPROVAL_REASON, ...result.denialReasons ?? []];
 }
+var DIMENSION_APPROVAL_REASON = "The agent's owner asked to approve this kind of request. The owner can approve or deny it in the AstraSync dashboard.";
+var DIMENSION_APPROVAL = /^pdlss\.[a-z_]+\.approval_required$/;
+function isDimensionApproval(result) {
+  const f = result.failures ?? [];
+  return f.some((x) => DIMENSION_APPROVAL.test(x.dimension)) && !f.some((x) => x.dimension === "commerce.intent.approval_required");
+}
+function onlyNeedsApproval(result) {
+  if (!result.policyAllowed || !requiresHumanApproval(result)) return false;
+  return (result.failures ?? []).every((f) => /\.approval_required$/.test(f.dimension));
+}
 
 // src/pdlss-pre-check.ts
 function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
@@ -2512,6 +2535,7 @@ function createMiddleware(options) {
       const attemptHeader = req.headers["x-astra-attempt-id"];
       const inboundAttemptId = typeof attemptHeader === "string" && /^att_[0-9a-f]{32}$/.test(attemptHeader) ? attemptHeader : void 0;
       const commerceArtifacts = detectExpressCommerce(req);
+      const heldByRoute = options.approvalHeldByRoute?.(req) === true;
       const verificationRequest = {
         credentials,
         ...commerceArtifacts && { commerceArtifacts },
@@ -2523,6 +2547,7 @@ function createMiddleware(options) {
         counterpartyType: config.counterpartyType || "api",
         enableRuntimeChallenge,
         ...routePolicyOf(routeConfig) && { routePolicy: routePolicyOf(routeConfig) },
+        ...heldByRoute && { approvalHeldByRoute: true },
         durationRequired: astraCreds?.pdlss?.duration?.maxSessionDuration,
         ...txValue !== void 0 && { transactionValue: txValue },
         ...txCurrency && { currency: txCurrency },
@@ -2579,6 +2604,9 @@ function createMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (heldByRoute && !result.stepUpApproval && onlyNeedsApproval(result)) {
+        return next();
+      }
       if (requiresHumanApproval(result)) {
         annotateApprovalRequired(result);
         if (shouldRecordDecisions && sessionId) {