@agentronics/sdk 0.5.0 → 0.7.0

package/dist/middleware-Dd2T772u.d.ts

@@ -0,0 +1,429 @@
+import { TraceEvent } from '@agentronics/protocol';
+
+type CrawlerCategory = 'ai' | 'search';
+interface CrawlerSignature {
+    /** Stable vendor id, reported as identity.vendor. */
+    name: string;
+    category: CrawlerCategory;
+    /** Tested against navigator.userAgent. */
+    pattern: RegExp;
+}
+
+/**
+ * Published crawler IP ranges.
+ *
+ * Most AI crawlers (GPTBot, ChatGPT-User, PerplexityBot, …) don't support
+ * reverse-DNS verification — instead the vendor publishes the CIDR blocks its
+ * crawler uses as JSON (`{ prefixes: [{ ipv4Prefix } | { ipv6Prefix }] }`).
+ * A User-Agent claim plus a client IP inside the vendor's published ranges is
+ * a verified crawler. Unlike rDNS this needs only `fetch`, so it also works on
+ * edge runtimes.
+ */
+/** Vendor range lists, keyed by crawler signature name. Fixed, vendor-owned URLs. */
+declare const PUBLISHED_IP_RANGES: Record<string, string[]>;
+interface IpRangeOptions {
+    /** Static CIDR lists per crawler name; replaces the fetched lists for those names. */
+    ipRanges?: Record<string, string[]>;
+    /** Test seam. */
+    fetcher?: typeof fetch;
+}
+/** The CIDR list for a crawler, or null when the vendor publishes none. */
+declare function rangesFor(name: string, options?: IpRangeOptions): Promise<string[] | null>;
+/** True when `ip` (v4 or v6) falls inside `cidr`. Mismatched families never match. */
+declare function ipInCidr(ip: string, cidr: string): boolean;
+declare const ipInRanges: (ip: string, cidrs: string[]) => boolean;
+
+/**
+ * Server-side crawler identification + verification.
+ *
+ * A User-Agent claim is trivially spoofable, so on its own it only makes a
+ * request "claimed". A claim becomes verified in one of two ways the vendor
+ * documents:
+ *
+ * 1. **Published IP ranges** — the client IP is inside the CIDR list the vendor
+ *    publishes as JSON (OpenAI, Perplexity, Google, Bing, DuckDuckGo, Common
+ *    Crawl). Needs only `fetch`, so it works on edge runtimes too.
+ * 2. **Forward-confirmed reverse DNS** — the IP's PTR name sits under the
+ *    vendor's domain AND resolves back to the same IP (Google, Microsoft,
+ *    Apple, Yandex, Baidu, Amazon). Needs Node DNS; on edge runtimes it
+ *    degrades to "unverified".
+ */
+
+/** Vendors that document reverse-DNS verification, keyed by signature name. */
+declare const RDNS_DOMAINS: Record<string, string[]>;
+interface CrawlerClaim {
+    name: string;
+    category: CrawlerSignature['category'];
+}
+declare function classifyUserAgent(ua: string | null, signatures?: CrawlerSignature[]): CrawlerClaim | null;
+/**
+ * Where the real client IP comes from. Platform headers are set by the edge
+ * and can't be spoofed by the caller; the leftmost X-Forwarded-For entry CAN,
+ * so it's never used by default.
+ */
+type ClientIpSource = 'auto' | 'cloudflare' | 'vercel' | ((request: Request) => string | null);
+declare function clientIp(request: Request, source?: ClientIpSource): string | null;
+interface DnsResolver {
+    reverse(ip: string): Promise<string[]>;
+    lookup(host: string): Promise<string[]>;
+}
+type CrawlerVerification = {
+    status: 'verified';
+    name: string;
+    host: string;
+    ip: string;
+    via: 'ip-range' | 'rdns';
+} | {
+    status: 'unverified';
+    name: string;
+    reason: string;
+};
+declare function verifyCrawler(claim: CrawlerClaim, ip: string | null, resolver?: DnsResolver, ranges?: IpRangeOptions): Promise<CrawlerVerification>;
+
+/**
+ * Structured Field Values for HTTP (RFC 9651) — the subset HTTP Message
+ * Signatures (RFC 9421) and Web Bot Auth need: Dictionaries, Inner Lists,
+ * Items, Parameters; bare items of type Integer, Decimal, String, Token,
+ * Byte Sequence and Boolean. Parsing is strict (invalid input throws), and
+ * serialization is canonical, which RFC 9421 relies on for `@signature-params`.
+ */
+declare class SfToken {
+    readonly value: string;
+    constructor(value: string);
+}
+declare class SfDecimal {
+    readonly value: number;
+    constructor(value: number);
+}
+type BareItem = string | number | boolean | Uint8Array | SfToken | SfDecimal;
+type Params = Array<[string, BareItem]>;
+interface Item {
+    value: BareItem;
+    params: Params;
+}
+interface InnerList {
+    items: Item[];
+    params: Params;
+}
+
+/**
+ * HTTP Message Signatures (RFC 9421) — request verification only.
+ * Runtime-neutral: WebCrypto + Fetch `Request`, so it runs on Node ≥ 20,
+ * Vercel/Next edge middleware, Cloudflare Workers, Deno and Bun.
+ */
+
+interface ComponentContext {
+    request: Request;
+    url: URL;
+    /** Override for `@authority` (e.g. when a proxy rewrites Host). */
+    authority?: string;
+}
+/** Build the signature base (RFC 9421 §2.5) for one Signature-Input member. */
+declare function signatureBase(input: InnerList, ctx: ComponentContext): string;
+interface PublicJwk {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    n?: string;
+    e?: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+    nbf?: number;
+    exp?: number;
+}
+type SignatureAlgorithm = 'ed25519' | 'rsa-pss-sha512' | 'rsa-v1_5-sha256' | 'ecdsa-p256-sha256' | 'ecdsa-p384-sha384';
+/** JWK SHA-256 thumbprint, base64url (RFC 7638; RFC 8037 §A.3 for OKP). */
+declare function jwkThumbprint(jwk: PublicJwk): Promise<string>;
+
+/**
+ * Web Bot Auth verifier — draft-meunier-webbotauth-httpsig-protocol-02.
+ *
+ * A signed agent request carries:
+ *   Signature-Agent: agent2="https://signer.example"        (dictionary form)
+ *   Signature-Input: sig2=("@authority" "signature-agent";key="agent2");
+ *                    created=…;expires=…;keyid="<JWK thumbprint>";tag="web-bot-auth"
+ *   Signature:       sig2=:<base64>:
+ * The verifier resolves the signer's key directory
+ * (<origin>/.well-known/http-message-signatures-directory by default), picks
+ * the key whose JWK thumbprint equals `keyid`, rebuilds the RFC 9421 signature
+ * base, and verifies it. Cheap checks run before any network call.
+ */
+
+declare const WEB_BOT_AUTH_TAG = "web-bot-auth";
+declare const DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+interface ReplayCache {
+    has(key: string): boolean | Promise<boolean>;
+    add(key: string, ttlSeconds: number): void | Promise<void>;
+}
+/** Bounded in-memory replay cache. Use a shared store (Redis…) across instances. */
+declare function memoryReplayCache(maxEntries?: number): ReplayCache;
+interface WebBotAuthOptions {
+    /**
+     * Which signers may be resolved. `'any'` (default) accepts any public HTTPS
+     * signer behind SSRF guards; a list restricts to those origins/URLs.
+     */
+    allowedDirectories?: 'any' | string[];
+    /** Accepted clock drift in seconds. Default 60. */
+    clockSkewSec?: number;
+    /** Max `expires - created`, seconds. Default 86400 (spec: ≤ 24 h recommended). */
+    maxValiditySec?: number;
+    /** Reject signatures without a `nonce`. Default false. */
+    requireNonce?: boolean;
+    replayCache?: ReplayCache;
+    /** Override `@authority` when a proxy rewrites Host. */
+    authority?: (request: Request, url: URL) => string;
+    /** Node only: DNS-check directory hosts for private addresses. Default true. */
+    resolveDns?: boolean;
+    /** Test seams. */
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+type WebBotAuthResult = {
+    status: 'absent';
+} | {
+    status: 'verified';
+    /** Stable identity: the signer URL (directory origin or JWKS URL). */
+    agentUrl: string;
+    keyid: string;
+    label: string;
+    alg: SignatureAlgorithm;
+    created: number;
+    expires: number;
+} | {
+    status: 'invalid';
+    reason: string;
+    agentUrl?: string;
+    keyid?: string;
+};
+declare function verifyWebBotAuth(request: Request, opts?: WebBotAuthOptions): Promise<WebBotAuthResult>;
+
+interface OAuth2Options {
+    issuer: string;
+    /** The audience / resource indicator this site accepts (RFC 8707). */
+    audience: string | string[];
+    /** Default `<issuer>/.well-known/jwks.json`. */
+    jwksUri?: string;
+    /** Static JWKS (tests / pinned keys) instead of fetching `jwksUri`. */
+    jwks?: {
+        keys: JsonWebKey[];
+    };
+    requiredScopes?: string[];
+    algorithms?: string[];
+    clockToleranceSec?: number;
+    /** Refuse tokens that aren't DPoP-bound. Default false (bound tokens are always checked). */
+    requireDpop?: boolean;
+}
+interface OAuthAgent {
+    id: string;
+    name: string;
+    vendor: string | null;
+    claims: Record<string, unknown>;
+    /** Present for delegated tokens: the user the agent acts for. */
+    onBehalfOf?: {
+        sub: string;
+        email?: string;
+        name?: string;
+    };
+    dpop: boolean;
+}
+declare function verifyOAuthToken(token: string, o: OAuth2Options, ctx: {
+    request: Request;
+    scheme: 'bearer' | 'dpop';
+    replayCache?: ReplayCache;
+}): Promise<OAuthAgent | {
+    error: string;
+}>;
+declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+interface ProtectedResourceOptions {
+    /** This site's resource identifier, e.g. `https://shop.example`. */
+    resource: string;
+    /** Authorization servers agents should get tokens from. */
+    authorizationServers: string[];
+    scopesSupported?: string[];
+    resourceName?: string;
+    /** Advertise DPoP support. Default true. */
+    dpop?: boolean;
+}
+/** JSON for `GET /.well-known/oauth-protected-resource`. */
+declare function protectedResourceMetadata(o: ProtectedResourceOptions): {
+    dpop_signing_alg_values_supported?: string[];
+    resource_name?: string;
+    scopes_supported?: string[];
+    resource: string;
+    authorization_servers: string[];
+    bearer_methods_supported: string[];
+};
+/**
+ * `WWW-Authenticate` value that tells an agent where to find the metadata
+ * (RFC 9728 §5.1). Send it with a 401 only on routes that *require* a token —
+ * Agentronics itself never blocks.
+ */
+declare function oauthChallenge(resource: string, opts?: {
+    error?: string;
+    scope?: string;
+}): string;
+
+/**
+ * Agent authentication for any HTTP request — the server half of the SDK.
+ *
+ *   const auth = createAgentAuth({ apiKey: { verify } })
+ *   const result = await auth.authenticate(request)   // Fetch API Request
+ *
+ * Authentication never blocks. A verified agent gets a stable identity your
+ * routes can read; an unverified agent (or a human) browses exactly as before.
+ *
+ * Methods, strongest first: Web Bot Auth (RFC 9421 signed agents), agent API
+ * keys, OAuth 2.1 access tokens (app-only or acting for a user, optionally
+ * DPoP-bound), and verified crawlers (published IP ranges or forward-confirmed
+ * reverse DNS). Everything runs on Node ≥ 20 and edge runtimes except crawler
+ * rDNS, which needs Node DNS (it degrades to "unverified", never "verified").
+ */
+
+type AgentAuthMethod = 'web-bot-auth' | 'api-key' | 'oauth2' | 'verified-crawler';
+interface VerifiedAgent {
+    /** Stable id: signer URL, API-key agent id, OAuth client id, or crawler name. */
+    id: string;
+    name: string;
+    vendor: string | null;
+    method: AgentAuthMethod;
+    claims?: Record<string, unknown>;
+    /** OAuth delegated tokens: the user this agent is acting for. */
+    onBehalfOf?: {
+        sub: string;
+        email?: string;
+        name?: string;
+    };
+}
+type AgentAuthResult = {
+    status: 'verified';
+    agent: VerifiedAgent;
+} | {
+    status: 'unverified';
+    reason: string;
+    claimedName?: string;
+    attempted: AgentAuthMethod[];
+} | {
+    status: 'none';
+};
+interface ApiKeyIdentity {
+    agentId: string;
+    name?: string;
+    vendor?: string;
+    scopes?: string[];
+}
+interface ApiKeyOptions {
+    /** Key prefix that marks a bearer token as an agent key. Default `agk_`. */
+    prefix?: string;
+    /** Look the key up. Return null for unknown/revoked keys. */
+    verify: (key: string) => ApiKeyIdentity | null | Promise<ApiKeyIdentity | null>;
+}
+interface CrawlerOptions extends IpRangeOptions {
+    /** Where to read the client IP. Default 'auto' (platform headers only). */
+    clientIp?: ClientIpSource;
+    /** Test seam / custom resolver. */
+    resolver?: DnsResolver;
+}
+interface AgentAuthOptions {
+    /** Web Bot Auth (on by default). `false` disables it. */
+    webBotAuth?: boolean | WebBotAuthOptions;
+    apiKey?: ApiKeyOptions;
+    /** One issuer, or several (e.g. your own auth server plus a partner's). */
+    oauth2?: OAuth2Options | OAuth2Options[];
+    /** Shared replay cache for Web Bot Auth nonces and DPoP proof ids. Default in-memory. */
+    replayCache?: ReplayCache;
+    /** Verified crawlers (on by default). `false` disables it. */
+    crawlers?: boolean | CrawlerOptions;
+}
+declare function createAgentAuth(options?: AgentAuthOptions): {
+    authenticate: (request: Request) => Promise<AgentAuthResult>;
+};
+/** SHA-256 hex of an agent key — store this, never the key. */
+declare function hashAgentKey(key: string): Promise<string>;
+/** Verifier over a static map of `sha256(key) → identity` (e.g. from env/config). */
+declare function staticKeyVerifier(hashedKeys: Record<string, ApiKeyIdentity>): ApiKeyOptions['verify'];
+/** Mint a new agent key (`agk_` + 32 random bytes, base64url). Show it once; store its hash. */
+declare function generateAgentKey(prefix?: string): string;
+declare const AGENT_HEADERS: {
+    readonly status: "x-agentronics-agent-status";
+    readonly id: "x-agentronics-agent-id";
+    readonly name: "x-agentronics-agent-name";
+    readonly vendor: "x-agentronics-agent-vendor";
+    readonly method: "x-agentronics-auth-method";
+};
+/**
+ * Request headers to forward downstream, with the auth result attached.
+ * Any incoming `x-agentronics-*` header is stripped first so a caller can
+ * never forge a verified identity.
+ */
+declare function withAgentHeaders(request: Request, result: AgentAuthResult): Headers;
+/**
+ * Read the forwarded result in a route handler (only trust it behind the
+ * middleware). Accepts anything with `get()` — `Headers`, Next's read-only
+ * `headers()`, or a plain adapter.
+ */
+declare function readAgentHeaders(headers: {
+    get(name: string): string | null;
+}): {
+    status: "verified" | "unverified" | "none";
+    id: string | null;
+    name: string | null;
+    vendor: string | null;
+    method: AgentAuthMethod | null;
+};
+/**
+ * Map a result to an SDK trace event so server-side auth shows up in the
+ * console's Auth + Logs pages next to in-browser agents. Returns null for
+ * non-agent traffic. Server-side agents use class `crawler` (HTTP fetchers);
+ * the method is in `metadata.protocol`.
+ */
+declare function toTraceEvent(result: AgentAuthResult, ctx: {
+    siteId: string;
+    request: Request;
+}): TraceEvent | null;
+
+/**
+ * Drop-in request handlers built on createAgentAuth().
+ *
+ * - createAgentAuthHandler(): framework-agnostic (Fetch Request in, identity out)
+ * - expressAgentAuth():        Express / Connect middleware
+ * - agentronicsMiddleware():   Next.js middleware — see '@agentronics/sdk/next'
+ *
+ * None of these ever block a request. They authenticate the agent (if any),
+ * attach the result as `x-agentronics-*` request headers, and pass every
+ * request through — verified agents, unverified agents and humans alike.
+ */
+
+interface AgentAuthHandlerOptions extends AgentAuthOptions {
+    /** Called for every agent request (not for plain human traffic). Never awaited on the hot path. */
+    onResult?: (event: {
+        result: AgentAuthResult;
+        request: Request;
+    }) => void | Promise<void>;
+    /** Return false to skip a path (e.g. static assets). */
+    matcher?: (url: URL) => boolean;
+}
+interface HandlerOutcome {
+    result: AgentAuthResult;
+    /** Request headers to forward downstream (spoofed x-agentronics-* stripped). */
+    headers: Headers;
+}
+declare function createAgentAuthHandler(options?: AgentAuthHandlerOptions): (request: Request) => Promise<HandlerOutcome>;
+interface NodeReq {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    protocol?: string;
+    headers: Record<string, string | string[] | undefined>;
+    agent?: AgentAuthResult;
+}
+/**
+ * Express middleware. Sets `req.agent` to the auth result and the
+ * `x-agentronics-*` request headers for downstream handlers, then always
+ * calls next(). For correct `@authority`/client IP behind a proxy, set
+ * Express `trust proxy`.
+ */
+declare function expressAgentAuth(options?: AgentAuthHandlerOptions): (req: NodeReq, _res: unknown, next: (err?: unknown) => void) => void;
+
+export { AGENT_HEADERS as A, protectedResourceMetadata as B, type ClientIpSource as C, DIRECTORY_PATH as D, rangesFor as E, readAgentHeaders as F, signatureBase as G, type HandlerOutcome as H, type IpRangeOptions as I, staticKeyVerifier as J, toTraceEvent as K, verifyCrawler as L, verifyOAuthToken as M, verifyWebBotAuth as N, type OAuth2Options as O, PROTECTED_RESOURCE_PATH as P, withAgentHeaders as Q, RDNS_DOMAINS as R, type SignatureAlgorithm as S, type VerifiedAgent as V, WEB_BOT_AUTH_TAG as W, type AgentAuthHandlerOptions as a, type AgentAuthMethod as b, type AgentAuthOptions as c, type AgentAuthResult as d, type ApiKeyIdentity as e, type ApiKeyOptions as f, type CrawlerOptions as g, type OAuthAgent as h, PUBLISHED_IP_RANGES as i, type ProtectedResourceOptions as j, type PublicJwk as k, type ReplayCache as l, type WebBotAuthOptions as m, type WebBotAuthResult as n, classifyUserAgent as o, clientIp as p, createAgentAuth as q, createAgentAuthHandler as r, expressAgentAuth as s, generateAgentKey as t, hashAgentKey as u, ipInCidr as v, ipInRanges as w, jwkThumbprint as x, memoryReplayCache as y, oauthChallenge as z };