@astrasyncai/adapter-lambda 1.2.0 → 2.1.0

package/README.md

@@ -1,8 +1,8 @@
 # @astrasyncai/adapter-lambda
 
-**AstraSync Commerce Shield edge adapter** — a Lambda@Edge/CloudFront
-interception shell that classifies and verifies inbound AI-agent traffic in
-front of your existing site. Zero site changes; **observe-only by default**.
+**AstraSync Trusted Agent Gateway (CloudFront adapter)** — a
+Lambda@Edge/CloudFront interception shell that classifies and verifies
+inbound AI-agent traffic in front of your existing site. Zero site changes; **observe-only by default**.
 
 Most of the web's traffic is now machines, and the analytics stack —
 GA4, session replay, attribution pixels, A/B tests — is structurally blind
@@ -13,12 +13,12 @@ adapter sits at your CDN edge and gives you the missing lens.
 
 Every request is classified into a visibility tier:
 
-| Tier                          | Signal                                                                                                                                                                                                                       | What happens                                                                             |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| **Verified**                  | `X-Astra-*` AstraSync credentials                                                                                                                                                                                            | Full verify-access round trip: identity, trust score, PDLSS mandate                      |
-| **Identified (unregistered)** | Payment-rail / signed-agent credentials (Visa Intelligent Commerce SD-JWTs, Mastercard Agent Pay & Visa TAP RFC 9421 signatures, Web Bot Auth, ACP, UCP, AP2, MPP, x402) or a platform-agent UA (Claude, ChatGPT, Gemini, …) | Recorded with protocol evidence; platform agents surface in your dashboard automatically |
-| **Anonymous bot**             | CLI/library/headless UA shapes                                                                                                                                                                                               | Sampled telemetry                                                                        |
-| **Human**                     | Browser-shaped traffic                                                                                                                                                                                                       | **Untouched — zero API calls, zero added latency**                                       |
+| Tier                          | Signal                                                                                                                                                                                                                       | What happens                                                                                           |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **Verified**                  | `X-Astra-*` AstraSync credentials                                                                                                                                                                                            | Full verify-access round trip: identity, trust score, PDLSS mandate                                    |
+| **Identified (unregistered)** | Payment-rail / signed-agent credentials (Visa Intelligent Commerce SD-JWTs, Mastercard Agent Pay & Visa TAP RFC 9421 signatures, Web Bot Auth, ACP, UCP, AP2, MPP, x402) or a platform-agent UA (Claude, ChatGPT, Gemini, …) | Recorded with protocol evidence; platform agents surface in your Visit Intelligence feed automatically |
+| **Anonymous bot**             | CLI/library/headless UA shapes                                                                                                                                                                                               | Sampled telemetry                                                                                      |
+| **Human**                     | Browser-shaped traffic                                                                                                                                                                                                       | **Untouched — zero API calls, zero added latency**                                                     |
 
 Static assets and any paths you configure are skipped entirely.
 

package/dist/index.d.mts

@@ -1,76 +1,20 @@
 import { CloudFrontRequestEvent, CloudFrontRequestResult, CloudFrontRequest, CloudFrontHeaders, CloudFrontResultResponse } from 'aws-lambda';
-import { EdgeConfig, EdgeMode, EdgeVerificationDepth } from '@astrasyncai/verification-gateway/edge-config';
-import { PlatformFingerprint } from '@astrasyncai/verification-gateway/platform-signatures';
-import { CommerceArtifactsPayload } from '@astrasyncai/verification-gateway';
+import { EdgeConfig } from '@astrasyncai/verification-gateway/edge-config';
+import { EdgeCoreOptions, Classification, DetectedCommerce, EffectivePolicy, TierOutcome } from '@astrasyncai/verification-gateway/edge-core';
+export { ASAT_HEADERS, Classification, DetectedCommerce, EdgeDecision, EffectivePolicy, TierOutcome, TrafficTier, buildDenyBody, buildManualReviewBody, resolvePolicy, sampled, withBudget } from '@astrasyncai/verification-gateway/edge-core';
 
 /**
- * Commerce Shield edge adapter (spec §7.4 / §33.5 #1) — shared types.
+ * Trusted Agent Gateway — CloudFront/Lambda@Edge adapter — shared types.
  *
- * The adapter is a thin interception shell: it classifies inbound traffic
- * into three visibility tiers, applies the dashboard-configured EdgeConfig
- * (mode/depth/path rules), forwards raw commerce artifacts to verify-access
- * (which does ALL cryptographic verification server-side, Step 0.5), and —
- * only in enforce mode — turns decisions into responses. In observe mode it
- * NEVER blocks and NEVER mutates responses.
+ * The adapter is a thin interception shell over the Trusted Agent Gateway
+ * edge core (`@astrasyncai/verification-gateway/edge-core`), which owns the
+ * platform-neutral classification/verification/enforcement pipeline. This
+ * package contributes the CloudFront platform I/O (event normalization,
+ * outcome application) plus Lambda@Edge-specific configuration (Secrets
+ * Manager, baked build-time constants).
  */
 
-/**
- * The three visibility tiers of the Commerce Shield live agent feed, plus
- * `human` (which the shell touches as little as possible) and `skipped`
- * (path-filtered — static assets etc.).
- */
-type TrafficTier = 'verified' | 'identified' | 'anonymous-bot' | 'human' | 'skipped';
-interface Classification {
-    tier: TrafficTier;
-    /** Detected transport/credential protocol (tier `identified`/`verified`). */
-    protocol?: string;
-    /** Platform UA fingerprint when one matched. */
-    fingerprint?: PlatformFingerprint;
-    /** Raw commerce artifacts detected on the wire, ready to forward. */
-    artifacts?: CommerceArtifactsPayload;
-    /** Light, crypto-free detection detail for the beacon (kid namespace etc). */
-    evidence?: Record<string, unknown>;
-}
-/** What the shell decided (observe mode records it; enforce mode acts on it). */
-type EdgeDecision = 'allow' | 'deny' | 'manual_review';
-interface TierOutcome {
-    tier: TrafficTier;
-    decision: EdgeDecision;
-    /** Why (deny/step-up reasons, or 'observe-passthrough'). */
-    reasons: string[];
-    /** ASAT header material when a verify-access call succeeded. */
-    asat?: {
-        trustScore?: number;
-        agentId?: string;
-        developerId?: string;
-        accessLevel?: string;
-    };
-    sessionId?: string;
-    protocol?: string;
-    guidance?: {
-        message?: string;
-        registrationUrl?: string;
-        documentationUrl?: string;
-    };
-    stepUp?: {
-        pollUrl?: string;
-        expiresAt?: string;
-    };
-    correlationId?: string;
-}
-/** Per-request effective policy after path-rule resolution. */
-interface EffectivePolicy {
-    mode: EdgeMode;
-    depth: EdgeVerificationDepth;
-    skip: boolean;
-}
-interface EdgeAdapterOptions {
-    /** AstraSync API base, e.g. `https://astrasync.ai/api`. */
-    apiBaseUrl: string;
-    /** The protected property's ASTRAE endpoint id. */
-    counterpartyId: string;
-    /** Canonical public URL of the protected property, e.g. `https://astrasync.shop`. */
-    counterpartyUrl: string;
+interface EdgeAdapterOptions extends EdgeCoreOptions {
     /**
      * Merchant API key (`kya_*`). Provide directly (tests/local) or via
      * `apiKeySecretName` (production — AWS Secrets Manager us-east-1, since
@@ -85,33 +29,21 @@ interface EdgeAdapterOptions {
     fetchSecret?: (secretName: string) => Promise<string | undefined>;
     /** Edge-config cache TTL (ms). Default 60s. */
     configTtlMs?: number;
-    /** Time budgets (ms). */
-    budgets?: {
-        /** Fire-and-forget beacon budget. Default 300. */
-        beaconMs?: number;
-        /** verify-access budget in observe mode. Default 1500. */
-        verifyObserveMs?: number;
-        /** verify-access budget in enforce mode. Default 3000. */
-        verifyEnforceMs?: number;
-    };
     /**
      * Compile-time fallback config used before the first successful
      * edge-config fetch and whenever the backend is unreachable with a cold
      * cache. Defaults to the SDK's DEFAULT_EDGE_CONFIG (observe/classify).
      */
     fallbackConfig?: EdgeConfig;
-    /** Random source for beacon sampling — injectable for tests. */
-    random?: () => number;
-    /** Structured log sink. Defaults to console. */
-    log?: (level: 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) => void;
 }
 
 /**
- * Commerce Shield edge shell — Lambda@Edge origin-request handler factory
- * (§7.4 / §33.5 #1).
+ * Trusted Agent Gateway edge shell — Lambda@Edge origin-request handler
+ * factory.
  *
  * Composition per request:
- *   config (cached) → path policy → classify → tier pipeline → apply outcome
+ *   config (cached) → edge core evaluation (path policy → classify → tier
+ *   pipeline) → apply outcome onto the CloudFront request
  *
  * THE invariant (tested): outside enforce mode the handler ALWAYS returns
  * the origin-bound request — any error, timeout, or misconfiguration
@@ -123,41 +55,27 @@ type EdgeHandler = (event: CloudFrontRequestEvent) => Promise<CloudFrontRequestR
 declare function createEdgeHandler(options: EdgeAdapterOptions): EdgeHandler;
 
 /**
- * Three-tier traffic classification (§33.5 #1: verified /
- * identified-but-unregistered / anonymous) plus the two non-tiers the shell
- * touches as little as possible: `human` (zero network calls, zero logging)
- * and `skipped` (static assets / excluded paths).
- *
- * Cheapest checks first — the human path must add microseconds, not
- * milliseconds. Platform signatures come from the SDK so the edge and the
- * backend's verify-access anonymous handler classify identically.
+ * Three-tier traffic classification — CloudFront wrapper over
+ * the edge core's classifier. The classification logic itself (tier order,
+ * UA patterns, path-rule resolution) lives in
+ * `@astrasyncai/verification-gateway/edge-core` and is shared with every
+ * edge platform adapter.
  */
 
-/**
- * Resolve the effective mode/depth for a path from the EdgeConfig — ordered
- * first-match-wins rules with case-insensitive globs; no match falls through
- * to the config's top-level defaults. Static extensions are always skipped
- * regardless of rules (a rule can only skip MORE, never un-skip an asset).
- */
-declare function resolvePolicy(config: EdgeConfig, path: string): EffectivePolicy;
-/**
- * Classify one request. Order (cheapest sufficient evidence wins):
- *   1. X-Astra-* credentials → `verified` candidate
- *   2. commerce-protocol credentials on the wire → `identified`
- *   3. platform UA fingerprint (Claude/ChatGPT/Gemini/…) → `identified`
- *   4. bot-shaped UA / headerless non-browser → `anonymous-bot`
- *   5. everything browser-shaped → `human`
- *
- * `depth: 'classify'` skips step 2 (no body decode, no header sniffing
- * beyond UA) — that is the zero-friction setting.
- */
+/** Classify one CloudFront origin-request. See the edge core for the tier order. */
 declare function classify(request: CloudFrontRequest, host: string, depth: 'classify' | 'authenticate' | 'authorize'): Classification;
 
 /**
- * CloudFront origin-request event helpers. The Lambda@Edge event shape puts
- * headers in `{ key, value }[]` arrays keyed by LOWERCASED header name, and
- * (with IncludeBody) the body arrives base64-encoded with an
- * `inputTruncated` flag when it exceeded CloudFront's ~1MB exposure cap.
+ * CloudFront platform I/O — the Lambda@Edge side of the edge core's
+ * PlatformIo contract, plus origin-request event helpers.
+ *
+ * The Lambda@Edge event shape puts headers in `{ key, value }[]` arrays
+ * keyed by LOWERCASED header name, and (with IncludeBody) the body arrives
+ * base64-encoded with an `inputTruncated` flag when it exceeded
+ * CloudFront's ~1MB exposure cap. `toNormalizedRequest` converts that into
+ * the core's NormalizedRequest; `applyCoreOutcome` executes the core's
+ * abstract outcome application against the CloudFront request/response
+ * primitives.
  */
 
 declare function getRequest(event: CloudFrontRequestEvent): CloudFrontRequest;
@@ -190,55 +108,27 @@ declare function stripHeadersByPrefix(request: CloudFrontRequest, prefix: string
 declare function jsonResponse(status: number, body: unknown, extraHeaders?: Record<string, string>): CloudFrontResultResponse;
 
 /**
- * Crypto-free commerce-protocol detection (§7.4.2 detection order).
- *
- * The edge only SNIFFS — header shapes, compact-JWT patterns, body field
- * names — and packages what it saw as raw `CommerceArtifactsPayload` for
- * verify-access, whose Step 0.5 pipeline does the authoritative parsing and
- * cryptographic verification server-side. Nothing here imports jose/sd-jwt/
- * signature libraries: detection must stay cheap enough to run on every
- * non-human request, and verification must happen exactly once, in the
- * canonical sink, where it is recorded.
+ * Crypto-free commerce-protocol detection (fixed detection order) —
+ * CloudFront wrapper over the edge core's detector. The sniffing logic
+ * (header shapes, compact-JWT patterns, body field names) lives in
+ * `@astrasyncai/verification-gateway/edge-core`; this module adapts the
+ * CloudFront event shape (separately-decoded body) onto it.
  */
 
-interface DetectedCommerce {
-    /** Detection-order label: rfc9421-agent-pay | rfc9421-tap | rfc9421-web-bot-auth | vi-sd-jwt | ap2 | acp | ucp | mpp | x402 */
-    protocol: string;
-    artifacts: CommerceArtifactsPayload;
-    /** Light detection detail for beacons/audit — never secrets or full credentials. */
-    evidence: Record<string, unknown>;
-}
 /**
- * §7.4.2 order (after the X-Astra native check, which classify.ts owns):
- * SD-JWT/VI → RFC 9421 (Agent Pay / TAP / Web Bot Auth by kid namespace or
- * Signature-Agent) → ACP HMAC → UCP session → AP2 body triple → MPP → x402.
- * Returns undefined when nothing commerce-shaped is on the wire.
- *
- * When the body was truncated by CloudFront (`inputTruncated`), body-bound
- * artifacts still forward what arrived but carry a `bodyTruncated` evidence
- * flag — the backend downgrades those signatures rather than hard-failing.
+ * Detect commerce-protocol credentials on a CloudFront origin-request.
+ * `body` is the caller-decoded request body (see `decodeBody`) — kept as an
+ * explicit parameter so callers that already decoded it don't pay twice.
  */
 declare function detectCommerce(request: CloudFrontRequest, host: string, body: DecodedBody): DetectedCommerce | undefined;
 
 /**
- * Depth-controlled verification per tier. The edge never verifies
- * credentials itself — it forwards what it detected to verify-access, the
- * canonical sole verification sink (backend Step 0.5 runs the commerce
- * pipeline, records events, provisions orphans, persists sessions). What
- * the depth setting controls is how much the edge LOOKS and how much it
- * FORWARDS:
- *
- *   classify     — what is it? UA tiers only. Zero verify-access calls;
- *                  beacons only.
- *   authenticate — who is it? + protocol detection. X-Astra agents get a
- *                  verify-access identity check; commerce/platform traffic
- *                  is beaconed with protocol + evidence (no signature
- *                  verification anywhere).
- *   authorize    — are they allowed? + artifact forwarding. X-Astra verify
- *                  calls carry commerceArtifacts; identified traffic gets an
- *                  anonymous verify-access call with artifacts +
- *                  callerMetadata so the backend cryptographically proves
- *                  and policy-evaluates once.
+ * Depth-controlled verification per tier — CloudFront wrapper over the edge
+ * core's tier pipeline. The verification semantics (what each depth looks
+ * at and forwards, the fail-open rules, the verify-access request shape)
+ * live in `@astrasyncai/verification-gateway/edge-core`; the edge never
+ * verifies credentials itself — verify-access is the canonical sole
+ * verification sink.
  */
 
 /**
@@ -253,20 +143,13 @@ declare function runTier(options: EdgeAdapterOptions, request: CloudFrontRequest
 }): Promise<TierOutcome>;
 
 /**
- * Decision → CloudFront result wiring (§7.4 enforcement, §7.4.7 ASAT
- * headers). Executed in BOTH modes so observe mode records exactly what
- * enforce mode would have done — but only enforce mode is allowed to return
- * anything other than the origin-bound request.
+ * Decision → CloudFront result wiring (enforcement + ASAT trust-attestation
+ * headers). The decision logic (observe shadow stamps, misconfig fail-open,
+ * enforce-mode response bodies) lives in the edge core; this module
+ * executes the core's abstract outcome application against CloudFront
+ * request/response primitives.
  */
 
-/** §7.4.7 ASAT trust-attestation headers injected on allowed requests. */
-declare const ASAT_HEADERS: {
-    readonly trustScore: "X-AstraSync-Trust-Score";
-    readonly agentId: "X-AstraSync-Agent-Id";
-    readonly developerId: "X-AstraSync-Developer-Id";
-    readonly permissions: "X-AstraSync-Permissions";
-    readonly observedDecision: "X-AstraSync-Observed-Decision";
-};
 /**
  * Apply the outcome. Always strips inbound spoofed `x-astrasync-*` headers
  * first (both modes — trust headers must only ever originate here).
@@ -280,51 +163,13 @@ declare const ASAT_HEADERS: {
 declare function applyOutcome(options: EdgeAdapterOptions, request: CloudFrontRequest, outcome: TierOutcome, policy: EffectivePolicy): CloudFrontRequestResult;
 
 /**
- * §7.4.6 — protocol-specific machine-readable messaging for enforce-mode
- * responses. Agents (not humans) consume these bodies: stable error codes,
- * the failure list, and registration guidance with real URLs.
- */
-
-interface DenyBody {
-    success: false;
-    error: {
-        code: 'UNAUTHORIZED' | 'INSUFFICIENT_ACCESS';
-        message: string;
-        protocol?: string;
-        failures: string[];
-        correlationId?: string;
-        guidance: {
-            message?: string;
-            registrationUrl?: string;
-            documentationUrl?: string;
-        };
-    };
-}
-declare function buildDenyBody(outcome: TierOutcome, apiBaseUrl: string): DenyBody;
-interface ManualReviewBody {
-    success: false;
-    status: 'manual_review';
-    message: string;
-    stepUpApproval?: {
-        pollUrl?: string;
-        expiresAt?: string;
-    };
-    correlationId?: string;
-}
-declare function buildManualReviewBody(outcome: TierOutcome): ManualReviewBody;
-
-/**
- * Time-budgeted event emission.
- *
- * Lambda@Edge has no `waitUntil` — anything not awaited before the handler
- * returns may never run (the container freezes). So every network call is
- * awaited under an explicit budget and DROPPED on timeout: latency to the
- * customer's traffic is bounded, and a slow AstraSync API costs telemetry,
- * never page loads.
+ * Time-budgeted event emission — CloudFront wrapper over the edge core's
+ * telemetry. Lambda@Edge has no `waitUntil`, so every network call is
+ * awaited under an explicit budget and DROPPED on timeout (the core's
+ * default posture): latency to the customer's traffic is bounded, and a
+ * slow AstraSync API costs telemetry, never page loads.
  */
 
-/** Await `promise` for at most `ms`; resolve `undefined` on timeout/error. */
-declare function withBudget<T>(promise: Promise<T>, ms: number): Promise<T | undefined>;
 /**
  * Emit an unregistered-attempt beacon for `identified` (non-crypto depths)
  * and sampled `anonymous-bot` traffic. Unauthenticated by design
@@ -332,8 +177,6 @@ declare function withBudget<T>(promise: Promise<T>, ms: number): Promise<T | und
  * find-or-provisions orphan platform agents server-side.
  */
 declare function emitBeacon(options: EdgeAdapterOptions, request: CloudFrontRequest, classification: Classification, budgetMs: number): Promise<void>;
-/** Deterministic-in-tests sampling gate. */
-declare function sampled(rate: number, random?: () => number): boolean;
 
 /**
  * Runtime configuration for the edge shell.
@@ -367,4 +210,4 @@ declare function loadEdgeConfig(options: EdgeAdapterOptions, apiKey: string | un
 /** Reset module caches — tests only. */
 declare function _resetConfigCaches(): void;
 
-export { ASAT_HEADERS, type Classification, type DetectedCommerce, type EdgeAdapterOptions, type EdgeDecision, type EdgeHandler, type EffectivePolicy, type TierOutcome, type TrafficTier, _resetConfigCaches, applyOutcome, buildDenyBody, buildManualReviewBody, classify, createEdgeHandler, decodeBody, detectCommerce, emitBeacon, flattenHeaders, getHeader, getRequest, jsonResponse, loadEdgeConfig, requestUrl, resolveApiKey, resolvePolicy, runTier, sampled, setHeader, stripHeadersByPrefix, withBudget };
+export { type EdgeAdapterOptions, type EdgeHandler, _resetConfigCaches, applyOutcome, classify, createEdgeHandler, decodeBody, detectCommerce, emitBeacon, flattenHeaders, getHeader, getRequest, jsonResponse, loadEdgeConfig, requestUrl, resolveApiKey, runTier, setHeader, stripHeadersByPrefix };