@astrasyncai/verification-gateway 4.0.0 → 4.2.0

package/dist/edge-core/index.d.ts

@@ -0,0 +1,425 @@
+import { EdgeMode, EdgeVerificationDepth, EdgeConfig } from '../edge-config.js';
+import { PlatformFingerprint } from '../platform-signatures.js';
+import { f as CommerceArtifactsPayload, w as VerificationRequest } from '../types-sMxBT-nM.js';
+import { verify } from '../verify.js';
+import { ObservedMetadata } from '../metadata-capture.js';
+
+/**
+ * Trusted Agent Gateway edge core — shared types.
+ *
+ * The edge core is the platform-neutral heart of the AstraSync edge
+ * adapters (Lambda@Edge/CloudFront, Cloudflare Workers, Vercel Edge,
+ * Fastly Compute). It classifies inbound traffic into 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), and — only in enforce mode —
+ * turns decisions into responses. In observe mode it NEVER blocks and
+ * NEVER mutates responses.
+ *
+ * Platform packages implement {@link PlatformIo}: they normalize their
+ * native request shape into a {@link NormalizedRequest}, run the core, and
+ * apply the returned {@link OutcomeApplication} back onto their native
+ * request/response primitives.
+ */
+
+/**
+ * The platform-neutral view of one inbound HTTP request.
+ *
+ * Invariants platform normalizers must uphold:
+ * - `headers` keys are LOWERCASED header names; multi-valued headers are
+ *   joined with `", "` (standard HTTP field-value concatenation).
+ * - `uri` is the path only (no query string); `querystring` has no
+ *   leading `?` and is empty when absent.
+ * - `bodyText` is the decoded UTF-8 body when one was available to the
+ *   platform, with `bodyTruncated: true` when the platform capped it.
+ * - `connection` carries transport-layer signals only the platform can
+ *   see (ip, country, asn, tlsVersion, httpVersion, city, …). Absent
+ *   values are simply omitted — a partial block is fine.
+ */
+interface NormalizedRequest {
+    method: string;
+    uri: string;
+    querystring: string;
+    headers: Record<string, string>;
+    bodyText?: string;
+    bodyTruncated?: boolean;
+    /** Client IP as the platform reports it (used for telemetry only). */
+    clientIp?: string;
+    /** Connection-layer metadata (country, asn, tlsVersion, …). */
+    connection?: Record<string, string>;
+}
+/**
+ * Contract between the core and a platform package: the platform converts
+ * its native request into a {@link NormalizedRequest} and applies the
+ * core's abstract {@link OutcomeApplication} back onto its native shapes.
+ */
+interface PlatformIo<NativeRequest = unknown, NativeResult = unknown> {
+    normalize(request: NativeRequest): NormalizedRequest | Promise<NormalizedRequest>;
+    apply(request: NativeRequest, application: OutcomeApplication): NativeResult;
+}
+/**
+ * What the platform must do with the request after evaluation.
+ *
+ * - `pass`: forward the request to the origin. First strip every inbound
+ *   header matching one of `stripHeaderPrefixes` (case-insensitive; a
+ *   caller must never be able to smuggle trust headers past the origin),
+ *   then set each header in `injectHeaders` (overwriting prior values).
+ *   Both maps are empty for traffic the gateway leaves untouched.
+ * - `respond`: short-circuit with an HTTP response. `bodyJson` must be
+ *   serialized as JSON and served with `Content-Type: application/json`;
+ *   `headers` are additional response headers (e.g. `Retry-After`).
+ */
+type OutcomeApplication = {
+    action: 'pass';
+    injectHeaders: Record<string, string>;
+    stripHeaderPrefixes: string[];
+} | {
+    action: 'respond';
+    status: number;
+    headers: Record<string, string>;
+    bodyJson: unknown;
+};
+/**
+ * The visibility tiers of the live agent-traffic feed, plus `human`
+ * (which the gateway 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 gateway 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[];
+    /**
+     * The property's own API key was rejected by verify-access (a merchant
+     * misconfiguration — neither an agent deny nor an infra failure). The
+     * outcome is `allow` (fail-open in BOTH modes — agents must not be
+     * blocked by the property's dead key) but the flag stamps
+     * `X-AstraSync-Observed-Decision: misconfig` for origin-side logs; the
+     * owner is alerted server-side on every rejected call.
+     */
+    misconfig?: boolean;
+    /** Trust-attestation 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;
+}
+/** Structured log sink shared by the core and the platform adapters. */
+type EdgeLogger = (level: 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) => void;
+/**
+ * Options the edge core needs to evaluate a request. Platform adapter
+ * option types extend this with their platform-specific configuration
+ * (secret fetching, origin backends, …).
+ */
+interface EdgeCoreOptions {
+    /** 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;
+    /** 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;
+    };
+    /**
+     * Background-work scheduler for runtimes that support it (e.g.
+     * `ctx.waitUntil` on Cloudflare Workers / Fastly Compute / Vercel Edge).
+     * When provided, telemetry beacons are scheduled through it instead of
+     * being awaited inline, removing them from the request's latency path
+     * entirely. Platforms without one (Lambda@Edge) leave this unset and
+     * beacons are awaited under their time budget.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** Random source for beacon sampling — injectable for tests. */
+    random?: () => number;
+    /** Structured log sink. */
+    log?: EdgeLogger;
+}
+
+/**
+ * Three-tier traffic classification (verified / identified-but-unregistered
+ * / anonymous) plus the two non-tiers the gateway 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 are shared with the backend so the
+ * edge and verify-access's anonymous handler classify identically.
+ */
+
+/**
+ * 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 inspection, no header sniffing
+ * beyond UA) — that is the zero-friction setting.
+ */
+declare function classify(req: NormalizedRequest, host: string, depth: 'classify' | 'authenticate' | 'authorize'): Classification;
+/** Exported for tests. */
+declare const _patterns: {
+    STATIC_EXTENSIONS: RegExp;
+    BOT_UA_PATTERN: RegExp;
+    BROWSER_UA_PATTERN: RegExp;
+};
+
+/**
+ * Crypto-free commerce-protocol detection.
+ *
+ * The edge only SNIFFS — header shapes, compact-JWT patterns, body field
+ * names — and packages what it saw as raw `CommerceArtifactsPayload` for
+ * verify-access, whose server-side pipeline does the authoritative parsing
+ * and cryptographic verification. 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.
+ */
+
+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>;
+}
+/**
+ * Detection order (after the native X-Astra check, which classify 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 platform truncated the body (`bodyTruncated`), body-bound
+ * artifacts still forward what arrived but carry a `bodyTruncated`
+ * evidence flag — the backend downgrades those signatures rather than
+ * hard-failing.
+ */
+declare function detectCommerce(req: NormalizedRequest, host: string): DetectedCommerce | undefined;
+
+/**
+ * The platform-neutral evaluation pipeline for one request:
+ *
+ *   path policy → classify → tier pipeline → outcome application
+ *
+ * Platform adapters own everything around this: config/secret loading,
+ * request normalization, and applying the returned application onto their
+ * native request/response shapes. `evaluateEdgeRequest` NEVER throws — any
+ * internal failure resolves to an untouched pass (the gateway must never
+ * take the site down).
+ */
+
+interface EdgeEvaluation {
+    application: OutcomeApplication;
+    policy: EffectivePolicy;
+    /** Absent when the path was skipped before classification. */
+    classification?: Classification;
+    /** Absent for skipped paths and human traffic (no pipeline run). */
+    outcome?: TierOutcome;
+}
+/**
+ * Evaluate one normalized request against the effective EdgeConfig.
+ *
+ * - Skipped paths (static assets / skip rules): untouched, zero work.
+ * - Humans: get out of the way. No calls, no logs, no header changes.
+ * - Everything else runs the tier pipeline and yields an application the
+ *   platform must execute (pass with header hygiene, or an enforce-mode
+ *   response).
+ */
+declare function evaluateEdgeRequest(options: EdgeCoreOptions, req: NormalizedRequest, config: EdgeConfig, apiKey: string | undefined): Promise<EdgeEvaluation>;
+
+/**
+ * Decision → abstract outcome-application wiring. Executed in BOTH modes
+ * so observe mode records exactly what enforce mode would have done — but
+ * only enforce mode is allowed to emit anything other than a pass.
+ */
+
+/** 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";
+};
+/**
+ * A pass that leaves the request completely untouched — used for skipped
+ * paths and human traffic, which the gateway must not modify at all.
+ */
+declare function passUntouched(): OutcomeApplication;
+/**
+ * Turn a tier outcome into the abstract application the platform executes.
+ * Every evaluated pass strips inbound spoofed `x-astrasync-*` headers
+ * (both modes — trust headers must only ever originate at the gateway).
+ *
+ * Observe mode: always a pass — header hygiene plus an
+ * `X-AstraSync-Observed-Decision` stamp for origin-side log correlation.
+ *
+ * Enforce mode: ALLOW → pass with trust-attestation headers; DENY → 403
+ * machine-readable body; MANUAL_REVIEW → 202 with step-up poll info.
+ */
+declare function applyOutcome(options: {
+    apiBaseUrl: string;
+}, outcome: TierOutcome, policy: EffectivePolicy): OutcomeApplication;
+
+/**
+ * Time-budgeted event emission.
+ *
+ * Some edge runtimes (Lambda@Edge) have no background-work scheduler —
+ * anything not awaited before the handler returns may never run. So every
+ * telemetry 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. Runtimes that provide
+ * `waitUntil` (Cloudflare Workers, Vercel Edge, Fastly Compute) can pass
+ * it via {@link EdgeCoreOptions.waitUntil} to take beacons off the latency
+ * path entirely.
+ */
+
+/** 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; the
+ * backend fingerprints the UA and find-or-provisions platform agents
+ * server-side.
+ */
+declare function emitBeacon(options: EdgeCoreOptions, req: NormalizedRequest, classification: Classification, budgetMs: number): Promise<void>;
+/** Deterministic-in-tests sampling gate. */
+declare function sampled(rate: number, random?: () => number): boolean;
+
+/**
+ * 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;
+
+/**
+ * Depth-controlled verification per tier. The edge never verifies
+ * credentials itself — it forwards what it detected to verify-access, the
+ * canonical sole verification sink (the backend runs the commerce
+ * pipeline, records events, provisions unregistered platform agents,
+ * 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.
+ */
+
+declare function buildVerificationRequest(options: EdgeCoreOptions, req: NormalizedRequest, classification: Classification, includeArtifacts: boolean): VerificationRequest;
+declare function outcomeFromVerifyResult(classification: Classification, result: Awaited<ReturnType<typeof verify>>): TierOutcome;
+/**
+ * Run the tier-appropriate verification/telemetry for one classified
+ * request. NEVER throws; on any failure returns an `allow` outcome with the
+ * failure recorded in `reasons` (infra failures fail open — a presented
+ * credential the BACKEND rejected is a deny, but an unreachable backend is
+ * not a rejection).
+ */
+declare function runTier(options: EdgeCoreOptions, req: NormalizedRequest, classification: Classification, policy: EffectivePolicy, apiKey: string | undefined, sampling: {
+    anonymousBeaconRate: number;
+}): Promise<TierOutcome>;
+
+/**
+ * Helpers over {@link NormalizedRequest} — header access, URL
+ * reconstruction, and the full sanitized metadata capture.
+ */
+
+/** Value of a header (name matched case-insensitively), or undefined. */
+declare function headerValue(req: NormalizedRequest, name: string): string | undefined;
+/** Full request URL as the origin will see it (scheme fixed to https). */
+declare function requestUrl(req: NormalizedRequest, host: string): string;
+/**
+ * The FULL sanitized metadata capture for one request: every inbound
+ * header (secrets stripped, credential headers reduced to a safe format
+ * prefix) plus the connection-layer block the platform collected. The
+ * edge is the richest capture point — the headers are already in memory —
+ * and this is pure string work, so it adds no page latency. Forwarded on
+ * both the verify-access call and the telemetry beacon.
+ */
+declare function buildObservedMetadata(req: NormalizedRequest): ObservedMetadata;
+
+export { ASAT_HEADERS, type Classification, type DenyBody, type DetectedCommerce, type EdgeCoreOptions, type EdgeDecision, type EdgeEvaluation, type EdgeLogger, type EffectivePolicy, type ManualReviewBody, type NormalizedRequest, type OutcomeApplication, type PlatformIo, type TierOutcome, type TrafficTier, _patterns, applyOutcome, buildDenyBody, buildManualReviewBody, buildObservedMetadata, buildVerificationRequest, classify, detectCommerce, emitBeacon, evaluateEdgeRequest, headerValue, outcomeFromVerifyResult, passUntouched, requestUrl, resolvePolicy, runTier, sampled, withBudget };