@astrasyncai/adapter-lambda 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,370 @@
+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';
+
+/**
+ * Commerce Shield edge adapter (spec §7.4 / §33.5 #1) — 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 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;
+    /**
+     * Merchant API key (`kya_*`). Provide directly (tests/local) or via
+     * `apiKeySecretName` (production — AWS Secrets Manager us-east-1, since
+     * Lambda@Edge forbids environment variables).
+     */
+    apiKey?: string;
+    apiKeySecretName?: string;
+    /**
+     * Injectable secret fetcher (tests). Defaults to an
+     * @aws-sdk/client-secrets-manager GetSecretValue call.
+     */
+    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).
+ *
+ * Composition per request:
+ *   config (cached) → path policy → classify → tier pipeline → apply outcome
+ *
+ * THE invariant (tested): outside enforce mode the handler ALWAYS returns
+ * the origin-bound request — any error, timeout, or misconfiguration
+ * results in pass-through. A top-level catch guarantees it even against
+ * bugs in the shell itself.
+ */
+
+type EdgeHandler = (event: CloudFrontRequestEvent) => Promise<CloudFrontRequestResult>;
+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.
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+
+declare function getRequest(event: CloudFrontRequestEvent): CloudFrontRequest;
+/** First value of a header (lowercase name), or undefined. */
+declare function getHeader(request: CloudFrontRequest, name: string): string | undefined;
+/**
+ * Flatten CloudFront headers into the `Record<string, string | string[]>`
+ * shape the SDK extractors and verify-access artifacts expect.
+ */
+declare function flattenHeaders(headers: CloudFrontHeaders): Record<string, string | string[]>;
+interface DecodedBody {
+    /** UTF-8 body text, undefined when there is no body. */
+    text?: string;
+    /** True when CloudFront truncated the body before handing it to the trigger. */
+    truncated: boolean;
+}
+declare function decodeBody(request: CloudFrontRequest): DecodedBody;
+/** Full request URL as the origin will see it (scheme fixed to https). */
+declare function requestUrl(request: CloudFrontRequest, host: string): string;
+/**
+ * Set a header on the origin-bound request (overwrites all prior values).
+ */
+declare function setHeader(request: CloudFrontRequest, name: string, value: string): void;
+/**
+ * Strip every inbound header matching a prefix (lowercase compare). Used to
+ * drop spoofed `x-astrasync-*` trust headers before the shell injects its
+ * own — in BOTH modes, so a caller can never smuggle trust past the origin.
+ */
+declare function stripHeadersByPrefix(request: CloudFrontRequest, prefix: string): void;
+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.
+ */
+
+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.
+ */
+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.
+ */
+
+/**
+ * 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: EdgeAdapterOptions, request: CloudFrontRequest, classification: Classification, policy: EffectivePolicy, apiKey: string | undefined, sampling: {
+    anonymousBeaconRate: number;
+}): 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.
+ */
+
+/** §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).
+ *
+ * Observe mode: returns the request untouched apart from header hygiene and
+ * an `X-AstraSync-Observed-Decision` stamp for origin-side log correlation.
+ *
+ * Enforce mode: ALLOW → request + ASAT headers; DENY → 403 machine-readable
+ * body; MANUAL_REVIEW → 202 with step-up poll info.
+ */
+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.
+ */
+
+/** 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
+ * (CSRF-exempt on the backend); the backend fingerprints the UA and
+ * 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.
+ *
+ * Lambda@Edge forbids environment variables, so configuration is layered:
+ *   1. Build-time constants baked into the bundle (apiBaseUrl,
+ *      counterpartyId, counterpartyUrl, apiKeySecretName) — see
+ *      `tsup.config.ts` define block and `infra/deploy.sh`.
+ *   2. The merchant API key from AWS Secrets Manager (us-east-1), fetched
+ *      lazily once per container and cached with a 15-minute TTL so
+ *      rotation needs no redeploy. Observe mode works fully without it —
+ *      the beacon endpoint is unauthenticated and verify() degrades
+ *      keyless — so a Secrets Manager outage can never take the shell down.
+ *   3. The dashboard EdgeConfig via the SDK's getEdgeConfig (60s TTL,
+ *      stale-while-revalidate, enforce→observe degradation after 24h
+ *      staleness, DEFAULT_EDGE_CONFIG fallback — all in the SDK).
+ */
+
+/**
+ * Resolve the merchant API key. Never throws — a missing/unreachable secret
+ * degrades to keyless operation (observe mode is fully functional without
+ * it; enforce mode without a key cannot fetch a config that enforces, so it
+ * degrades to observe by construction).
+ */
+declare function resolveApiKey(options: EdgeAdapterOptions): Promise<string | undefined>;
+/**
+ * Load the effective EdgeConfig. Delegates caching/fallback/degradation to
+ * the SDK; adds the compile-time fallback override and never throws.
+ */
+declare function loadEdgeConfig(options: EdgeAdapterOptions, apiKey: string | undefined): Promise<EdgeConfig>;
+/** 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 };