@astrasyncai/verification-gateway 3.12.0 → 4.1.0

package/README.md

@@ -6,18 +6,19 @@ The AstraSync KYA Platform SDK. One package, two roles: register agents with the
 
 As of v2.4.0 this is the only npm package you need for AstraSync integration. Pick the subpath that matches what you're doing:
 
-| If you're…                                                                                | Import from                                      | Get                                                                                           |
-| ----------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| **Registering an agent with the KYA backend**                                             | `@astrasyncai/verification-gateway/registration` | `AstraSync` class — `register()`, `verify()`, `health()`. The `astrasync` CLI is bundled too. |
-| **Building an agent that calls out to other services** (per-request credential injection) | `@astrasyncai/verification-gateway/agent`        | `AgentClient`, `ChallengeHandler`, ownership validation, runtime PDLSS shape.                 |
-| **Running an Express API that AI agents call into**                                       | `@astrasyncai/verification-gateway/express`      | `createMiddleware()` — protect routes, attach verification context.                           |
-| **Running a Next.js app that AI agents call into**                                        | `@astrasyncai/verification-gateway/nextjs`       | `createMiddleware()`, Commerce Shield wiring.                                                 |
-| **Running an MCP server that AI agents call into**                                        | `@astrasyncai/verification-gateway/mcp`          | MCP tool gates + inner-hop dedupe headers.                                                    |
-| **Doing direct verification (no framework)**                                              | `@astrasyncai/verification-gateway/sdk`          | `VerificationGatewayClient` with retry / backoff / timeout.                                   |
-| **Parsing protocol-level credentials** (HTTP / A2A / MCP / x402 / AP2 / MPP)              | `@astrasyncai/verification-gateway/transport`    | Cross-protocol credential extraction + injection.                                             |
-| **Evaluating PDLSS offline** (local / hybrid mode)                                        | `@astrasyncai/verification-gateway/gateway`      | `AstraSyncGateway` (online / local / hybrid).                                                 |
-| **Governing Claude Code with a local policy**                                             | `@astrasyncai/verification-gateway/claude-code`  | PreToolUse-hook adapter; `astrasync-guard install-claude-code` sets it up.                    |
-| **Receiving webhook callbacks**                                                           | `@astrasyncai/verification-gateway/webhooks`     | `verifyAstraSyncWebhook()`, `signAstraSyncWebhook()`.                                         |
+| If you're…                                                                                | Import from                                                          | Get                                                                                                                                |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **Registering an agent with the KYA backend**                                             | `@astrasyncai/verification-gateway/registration`                     | `AstraSync` class — `register()`, `verify()`, `health()`. The `astrasync` CLI is bundled too.                                      |
+| **Building an agent that calls out to other services** (per-request credential injection) | `@astrasyncai/verification-gateway/agent`                            | `AgentClient`, `ChallengeHandler`, ownership validation, runtime PDLSS shape.                                                      |
+| **Running an Express API that AI agents call into**                                       | `@astrasyncai/verification-gateway/express`                          | `createMiddleware()` — protect routes, attach verification context.                                                                |
+| **Running a Next.js app that AI agents call into**                                        | `@astrasyncai/verification-gateway/nextjs`                           | `createMiddleware()`, verification-interstitial wiring.                                                                            |
+| **Running an MCP server that AI agents call into**                                        | `@astrasyncai/verification-gateway/mcp`                              | MCP tool gates + inner-hop dedupe headers.                                                                                         |
+| **Doing direct verification (no framework)**                                              | `@astrasyncai/verification-gateway/sdk`                              | `VerificationGatewayClient` with retry / backoff / timeout.                                                                        |
+| **Parsing protocol-level credentials** (HTTP / A2A / MCP / x402 / AP2 / MPP)              | `@astrasyncai/verification-gateway/transport`                        | Cross-protocol credential extraction + injection.                                                                                  |
+| **Evaluating PDLSS offline** (local / hybrid mode)                                        | `@astrasyncai/verification-gateway/gateway`                          | `AstraSyncGateway` (online / local / hybrid).                                                                                      |
+| **Governing Claude Code with a local policy**                                             | `@astrasyncai/verification-gateway/claude-code`                      | PreToolUse-hook adapter; `astrasync-guard install-claude-code` sets it up.                                                         |
+| **Receiving webhook callbacks**                                                           | `@astrasyncai/verification-gateway/webhooks`                         | `verifyAstraSyncWebhook()`, `signAstraSyncWebhook()`.                                                                              |
+| **Building on the Trusted Agent Gateway edge machinery**                                  | `.../edge-config`, `.../platform-signatures`, `.../metadata-capture` | Dashboard-managed edge policy, platform fingerprint registry, shared header sanitiser — see [Metadata capture](#metadata-capture). |
 
 > All subpaths talk to the same backend — `POST /agents/verify-access` for verification, `POST /agents/register` for registration. The contract is shared; the role is just which side of the handshake you're sitting on.
 
@@ -28,7 +29,7 @@ Before v2.4.0 the agent-registration half shipped as a separate package (`@astra
 The Verification Gateway provides a single, universal solution for verifying AI agents. One codebase, multiple deployment targets:
 
 - **Express.js middleware** - Protect API endpoints
-- **Next.js middleware** - Protect web applications with Commerce Shield
+- **Next.js middleware** - Protect web applications with the verification interstitial
 - **SDK functions** - Direct verification for agent-to-agent or serverless
 
 All verification flows through the same `POST /agents/verify-access` endpoint, ensuring consistent PDLSS (Permission, Duration, Limit, Scope, Self-instantiation) enforcement.
@@ -75,7 +76,7 @@ export const middleware = createMiddleware({
   apiBaseUrl: 'https://api.astrasync.ai',
   apiKey: process.env.ASTRASYNC_API_KEY,
   counterpartyId: 'ASTRAE-...',
-  showCommerceShield: true,
+  showInterstitial: true,
 });
 
 export const config = {
@@ -312,14 +313,14 @@ the claimed agent. The marker only gates the dedupe-skip decision.
 
 ## Access Levels
 
-| Level       | Description                       |
-| ----------- | --------------------------------- |
-| `none`      | No credentials provided           |
-| `guidance`  | Commerce Shield overlay shown     |
-| `read-only` | Can browse, no mutations          |
-| `standard`  | Normal access per PDLSS           |
-| `full`      | Full access for high-trust agents |
-| `internal`  | Organization member access        |
+| Level        | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `none`       | No credentials provided                         |
+| `restricted` | Minimal access; verification interstitial shown |
+| `read-only`  | Can browse, no mutations                        |
+| `standard`   | Normal access per PDLSS                         |
+| `full`       | Full access for high-trust agents               |
+| `internal`   | Organization member access                      |
 
 ## Trust Levels
 
@@ -335,10 +336,15 @@ the claimed agent. The marker only gates the dedupe-skip decision.
 The package includes React components for displaying verification status:
 
 ```tsx
-import { CommerceShield, TrustLevelBadge, GuidanceCard } from '@astrasyncai/verification-gateway/ui';
-
-// Commerce Shield overlay
-<CommerceShield
+import {
+  VerificationInterstitial,
+  TrustLevelBadge,
+  GuidanceCard,
+} from '@astrasyncai/verification-gateway/ui';
+
+// Verification interstitial overlay (renamed from CommerceShield in 4.1.0;
+// the old component/hook/props names still work as deprecated aliases)
+<VerificationInterstitial
   visible={!verified}
   result={verificationResult}
   onRegister={() => window.location.href = '/register'}
@@ -561,16 +567,81 @@ interface GatewayConfig {
 }
 ```
 
-## Commerce Shield
+## Verification interstitial
 
-When an unverified agent visits a protected page, the Commerce Shield overlay displays:
+When an unverified agent visits a protected web page, the Next.js middleware serves the **verification interstitial** — an HTML overlay (user-visible title: "AstraSync Agent Verification") that displays:
 
 - Registration guidance
 - Steps to get verified
 - Link to documentation
 - Optional guest access
 
-This creates a smooth experience for agents while maintaining security.
+This creates a smooth experience for agents while maintaining security. Control it with `showInterstitial` (default `true`) on the Next.js middleware options; the React building blocks ship on the `./ui` subpath (see [UI Components](#ui-components)).
+
+> **Renamed in 4.1.0** — this feature was previously called "Commerce Shield". The old names still work as deprecated aliases and will be removed in the next major: `showCommerceShield` (option; `showInterstitial` wins when both are set), `CommerceShield` / `useCommerceShield` / `CommerceShieldProps` (from `./ui` and the root barrel).
+
+## Trusted Agent Gateway (edge adapters)
+
+The **Trusted Agent Gateway (TAG)** is AstraSync's verification gateway at the CDN edge: it classifies and (optionally) verifies every inbound agent request in front of your existing site — in **observe** mode (verify, classify, and record everything; block nothing) or **enforce** mode — with zero site changes. Two packages deploy it:
+
+- [`@astrasyncai/adapter-lambda`](https://www.npmjs.com/package/@astrasyncai/adapter-lambda) — CloudFront / Lambda@Edge (CloudFormation template + deploy script included).
+- [`@astrasyncai/adapter-edge`](https://www.npmjs.com/package/@astrasyncai/adapter-edge) — Vercel Edge Middleware, Cloudflare Workers, and Fastly Compute, via per-platform subpaths (shipping in this release).
+
+Both consume the same dashboard-managed policy (`./edge-config`), the same platform fingerprint registry (`./platform-signatures`), and the same header sanitiser (`./metadata-capture`) as this SDK — one classification everywhere.
+
+### What each integration captures
+
+| Integration                                      | Header-level capture (`ObservedMetadata`)                   | Connection layer (IP / ASN / country / TLS / HTTP version / device class)                                                                                              |
+| ------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Edge adapters (`adapter-lambda`, `adapter-edge`) | Yes                                                         | **Yes** — native platform signals (the authoritative source)                                                                                                           |
+| `express` + `nextjs` SDK adapters                | Yes — **automatic on every verify** (no config, no opt-out) | Derived from CDN-injected headers when your origin sits behind Cloudflare / Fastly / Vercel / CloudFront (`deriveConnectionFromHeaders`, from 4.1.0); absent otherwise |
+| `mcp` SDK adapter                                | Yes — from 4.1.0                                            | Same CDN-header derivation as express/nextjs                                                                                                                           |
+
+> **Note:** `runCommercePipeline` (on the `./transport` subpath) is the **server-side** orchestrator of commerce-protocol verification — it runs inside the AstraSync verify-access service. The edge adapters forward raw commerce artifacts to verify-access and never bundle or call the pipeline themselves.
+
+### Which `EdgeConfig` fields each integration consumes
+
+The dashboard-managed `EdgeConfig` drives the **edge** posture. The observe/enforce × depth posture is **edge-only by design**: SDK adapters enforce via your dashboard **route policy** (fetched automatically on startup), not via `EdgeConfig` — the SDK consumes only the `sampling` block, which governs its anonymous traffic beacon.
+
+| `EdgeConfig` field             | Edge adapters (`adapter-lambda`, `adapter-edge`) | SDK adapters (`express` / `nextjs` / `mcp`)       |
+| ------------------------------ | ------------------------------------------------ | ------------------------------------------------- |
+| `mode` (`observe` / `enforce`) | Yes — the deployment posture                     | — (enforcement comes from dashboard route policy) |
+| `depth`                        | Yes — classify / authenticate / authorize        | —                                                 |
+| `pathRules`                    | Yes — per-path mode/depth/skip overrides         | —                                                 |
+| `sampling.anonymousBeaconRate` | Yes — anonymous-bot beacon sampling              | Yes — governs the SDK anonymous beacon            |
+| `failurePosture`               | Yes — always fail-open in v1                     | —                                                 |
+
+## Metadata capture
+
+Three subpath exports back the capture machinery (all edge-safe — no Node built-ins — and also re-exported flat from the package root):
+
+### `./metadata-capture`
+
+The ONE sanitiser deciding what is safe to store from an inbound agent's request. Used identically by the edge adapters, the SDK adapters, and the backend.
+
+- `sanitizeHeaders(raw)` → `{ headers, apiKeyFormat?, platformHeaders? }` — drops genuine secrets (cookies, signatures, AstraSync credential headers), reduces credential headers to a safe **format prefix** (e.g. `sk-ant-api03` — a platform signal, never the key), keeps everything else verbatim, and enforces size caps (`MAX_HEADERS`, `MAX_HEADER_VALUE_BYTES`, `MAX_TOTAL_BYTES`).
+- `extractApiKeyFormat(value)` — the safe key-format prefix of a credential header value, or `undefined` for unrecognised/opaque tokens.
+- `extractPlatformHeaders(sanitized)` — the platform-signal subset (`openai-organization`, `anthropic-version`, `x-goog-user-project`, …) of an already-sanitised map.
+- `deriveConnectionFromHeaders(headers)` — promotes CDN-injected headers (Cloudflare / Fastly / Vercel / CloudFront geo, client-IP, and TLS-fingerprint headers, incl. `cf-ja3-hash` / `cf-ja4`) into the `connection` block, so SDK-only deployments behind a CDN still get connection-layer attribution. Native edge signals remain authoritative; this is the SDK-level fallback.
+- `buildSdkObservedMetadata(rawHeaders)` — the one builder the express / nextjs / mcp adapters share: sanitised headers + `apiKeyFormat` + `platformHeaders` + derived `connection` + `schemaVersion`.
+- `CAPTURE_SCHEMA_VERSION` — the capture-semantics version stamped on every `ObservedMetadata` (currently `1`). Capture semantics are **frozen within a major version**: `schemaVersion` bumps only on a semantic change to what is kept/dropped/derived, never for additive signals. The verify body's `sdkVersion` disambiguates builds.
+- Types: `ObservedMetadata` (`{ headers, apiKeyFormat?, platformHeaders?, connection?, schemaVersion? }` — `connection` is populated natively by edge adapters and via CDN-header derivation by SDK adapters), `SanitizeHeadersResult`.
+
+### `./platform-signatures`
+
+The shared registry of known platform-agent fingerprints (Claude / ChatGPT / Gemini / Cursor / Goose / Perplexity) — the single source of truth for backend and edge classification.
+
+- `PLATFORM_AGENT_SIGNATURES` — the seed signature set (UA patterns, agent-card patterns, API-key-format patterns, header patterns).
+- `detectPlatformFingerprint(input)` → `{ vendor, fingerprintKey, displayName } | undefined` — first-match-wins detection over the seed set.
+- `matchPlatformSignature(signatures, input)` — the same matcher over a caller-supplied signature set (for merged/dynamic registries).
+
+### `./edge-config`
+
+The per-endpoint policy a Trusted Agent Gateway deployment fetches from the AstraSync dashboard.
+
+- `getEdgeConfig(config, counterpartyId)` — cached fetch (TTL + stale-while-revalidate). Fail posture is asymmetric by design: an unreachable backend can never turn enforcement ON, and a config stale for >24h automatically degrades any `enforce` back to `observe`.
+- `fetchEdgeConfig(...)` — one uncached fetch (ETag/304 aware); `matchEdgePathRule(rules, path)` — first-match-wins `*`-glob path rules; `degradeToObserve(config)`; `isEdgeConfig(value)`; `DEFAULT_EDGE_CONFIG` (observe-only, classify depth).
+- Types: `EdgeConfig` (`{ version, mode, depth, pathRules, sampling, failurePosture }`), `EdgeMode` (`'observe' | 'enforce'`), `EdgeVerificationDepth` (`'classify' | 'authenticate' | 'authorize'`), `EdgePathRule`.
 
 ## Two `baseUrl` conventions — same package, different clients
 
@@ -627,6 +698,12 @@ The installer registers the `astrasync-claude-hook` binary in Claude Code's `set
 
 ## Changelog
 
+### 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.

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-Djw4GLtz.mjs';
-import '../types-BntuzEEn.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-DqfPU5Bl.mjs';
+import '../types-r850cOt0.mjs';
 import '../metadata-capture.mjs';
 
 /**

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-DHu7m9HI.js';
-import '../types-SDu4Llbe.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-BLUx92FJ.js';
+import '../types-sMxBT-nM.js';
 import '../metadata-capture.js';
 
 /**

package/dist/adapters/express.d.mts

@@ -1,4 +1,4 @@
 import 'express';
-import '../types-BntuzEEn.mjs';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-B39o89gf.mjs';
+import '../types-r850cOt0.mjs';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-D_4hTn5Z.mjs';
 import '../metadata-capture.mjs';

package/dist/adapters/express.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-import '../types-SDu4Llbe.js';
-export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BuxKNO_q.js';
+import '../types-sMxBT-nM.js';
+export { c as createMiddleware, a as extractAstraSyncCredentials } from '../express-BVd1_3FE.js';
 import '../metadata-capture.js';