@agentronics/sdk 0.6.0 → 0.7.1

package/dist/server.d.cts

@@ -1,336 +1,131 @@
-import { TraceEvent } from '@agentronics/protocol';
+export { A as AGENT_HEADERS, a as AgentAuthHandlerOptions, b as AgentAuthMethod, c as AgentAuthOptions, d as AgentAuthResult, e as ApiKeyIdentity, f as ApiKeyOptions, C as ClientIpSource, g as CrawlerOptions, D as DIRECTORY_PATH, H as HandlerOutcome, I as IpRangeOptions, O as OAuth2Options, h as OAuthAgent, P as PROTECTED_RESOURCE_PATH, i as PUBLISHED_IP_RANGES, j as ProtectedResourceOptions, k as PublicJwk, R as RDNS_DOMAINS, l as ReplayCache, S as SignatureAlgorithm, V as VerifiedAgent, W as WEB_BOT_AUTH_TAG, m as WebBotAuthOptions, n as WebBotAuthResult, o as classifyUserAgent, p as clientIp, q as createAgentAuth, r as createAgentAuthHandler, s as expressAgentAuth, t as generateAgentKey, u as hashAgentKey, v as ipInCidr, w as ipInRanges, x as jwkThumbprint, y as memoryReplayCache, z as oauthChallenge, B as protectedResourceMetadata, E as rangesFor, F as readAgentHeaders, G as signatureBase, J as staticKeyVerifier, K as toTraceEvent, L as verifyCrawler, M as verifyOAuthToken, N as verifyWebBotAuth, Q as withAgentHeaders } from './middleware-Dd2T772u.cjs';
+import { PolicyRule, AgentIdentity } 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;
-}
-
-/**
- * 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 by forward-confirmed reverse DNS
- * (the IP's PTR name sits under the vendor's documented domain AND resolves
- * back to the same IP) — the method Google, Microsoft, Apple, Yandex, Baidu and
- * Amazon document for their crawlers. Needs Node DNS; on edge runtimes the
- * claim stays unverified (use Web Bot Auth, which works everywhere).
- */
-
-/** 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;
-} | {
-    status: 'unverified';
-    name: string;
-    reason: string;
-};
-declare function verifyCrawler(claim: CrawlerClaim, ip: string | null, resolver?: DnsResolver): 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 {
+interface TraceRelayOptions {
+    url: string;
+    ingestKey: string;
+    /** Events are re-labelled with this site id, whatever the browser sent. */
+    siteId: string;
+    /** Max events accepted per request. Default 100. */
+    maxEvents?: number;
     /**
-     * Which signers may be resolved. `'any'` (default) accepts any public HTTPS
-     * signer behind SSRF guards; a list restricts to those origins/URLs.
+     * Also hand every accepted batch to your own sink — a warehouse, a queue,
+     * a webhook. Runs alongside the console export; failures are ignored.
      */
-    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;
+    forward?: (events: Array<Record<string, unknown>>) => unknown;
+    fetcher?: typeof fetch;
 }
-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>;
+declare function createTraceRelay(options: TraceRelayOptions): (request: Request) => Promise<Response>;
 
 /**
- * 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
+ * The WebMCP `ModelContext` surface, per the W3C WebMCP draft (Oct 2026):
  *
- * Authentication never blocks. A verified agent gets a stable identity your
- * routes can read; an unverified agent (or a human) browses exactly as before.
+ *   await document.modelContext.registerTool(tool, { signal, exposedTo })
  *
- * Methods, strongest first: Web Bot Auth (RFC 9421 signed agents), agent API
- * keys, OAuth2 client-credentials JWTs, and verified crawlers (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").
+ * - The getter lives on `document`. `navigator.modelContext` was the old name;
+ *   Chrome 150 kept it as an alias and Chrome 152 removed it, so it's read
+ *   only as a fallback.
+ * - `registerTool()` is async. There is no `unregisterTool()`; aborting the
+ *   `signal` passed at registration unregisters the tool.
+ * - `toolactivated` / `toolcancel` events fire on the ModelContext when an
+ *   agent starts or cancels a tool call — the only reliable "an agent is here"
+ *   signal, because the API itself exists for every visitor of a WebMCP browser.
+ * - The declarative form API (`<form toolname>`) was removed from the spec
+ *   (Oct 8, 2026) and lives on only as an explainer; the SDK registers every
+ *   tool imperatively.
  */
+interface ToolAnnotations {
+    /** The tool only reads; agents may call it without asking the user. */
+    readOnlyHint?: boolean;
+    /** The tool's output includes content the site didn't author (reviews, messages, …). */
+    untrustedContentHint?: boolean;
+    /** Payments, deletes, sends — the agent should confirm with the user first. */
+    consequentialHint?: boolean;
+    /** Exposed only to agent debugging tools. */
+    debugging?: boolean;
+}
 
-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;
+interface GovernedTool<Input = unknown, Output = unknown> {
     name: string;
-    vendor: string | null;
-    method: AgentAuthMethod;
-    claims?: Record<string, unknown>;
+    /** Human-readable name agents and browsers may show (WebMCP `title`). */
+    title?: string;
+    version?: string;
+    group?: string;
+    description?: string;
+    /** WebMCP hints: readOnlyHint, consequentialHint, untrustedContentHint. */
+    annotations?: ToolAnnotations;
+    /** Other origins whose agents may see this tool (WebMCP `exposedTo`). */
+    exposedTo?: string[];
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    stage?: string;
+    authz?: Omit<PolicyRule, 'id' | 'tool'>;
+    rateLimit?: PolicyRule['rateLimit'];
+    execute: (input: Input, context: {
+        identity: AgentIdentity | null;
+        signal?: AbortSignal;
+    }) => Promise<Output> | Output;
 }
-type AgentAuthResult = {
-    status: 'verified';
-    agent: VerifiedAgent;
-} | {
-    status: 'unverified';
-    reason: string;
-    claimedName?: string;
-    attempted: AgentAuthMethod[];
-} | {
-    status: 'none';
-};
+
+/** Mirrors ApiKeyIdentity in @agentronics/sdk/server (kept structural to avoid a server import). */
 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 OAuth2Options {
-    issuer: string;
-    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;
-}
-interface CrawlerOptions {
-    /** 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;
-    oauth2?: OAuth2Options;
-    /** 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.
+ * Push the authoritative tool registry + site-memory snapshot to the
+ * Agentronics console — the full data the WebMCP Tools + Knaph pages need,
+ * which is too large for the lightweight trace stream. Call after `syncTools()`
+ * / `provideSiteMemory(...)`. Backend/server use only (the key is secret).
  */
-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;
+interface IntelSync {
+    /** POST the registry to /v1/sdk/tools. Returns the number of tools sent. */
+    pushTools(tools: GovernedTool[]): Promise<number>;
+    /** POST the site-memory snapshot (+ optional quality score) to /v1/sdk/memory. */
+    pushMemory(snapshot: object, score?: number): Promise<void>;
+    /**
+     * Fetch what the console manages for this site: authorization rules and the
+     * tool descriptions you approved in Procedural memory. Pass them to the
+     * browser SDK — `init({ policies, toolDescriptions })`.
+     */
+    pullConfig(): Promise<DashboardConfig>;
+    /**
+     * An agent-API-key verifier for `createAgentAuth({ apiKey: { verify } })`
+     * that checks keys minted in the console, live — revoking a key in the
+     * console takes effect within `cacheSeconds` (default 60).
+     */
+    keyVerifier(options?: {
+        cacheSeconds?: number;
+    }): (key: string) => Promise<ApiKeyIdentity | null>;
+}
+interface DashboardConfig {
+    policies: PolicyRule[];
+    /** tool name → approved description (replaces the code's description when published). */
+    toolDescriptions: Record<string, string>;
+    /** The site-memory snapshot last pushed for this site (null if none). */
+    siteMemory: Record<string, unknown> | null;
+    fetchedAt: string;
+}
 
 /**
- * Drop-in request handlers built on createAgentAuth().
+ * Serve `/.well-known/agent-context.json` — your site memory, for any agent,
+ * with no SDK on their side — from what you manage in the Agentronics console.
  *
- * - createAgentAuthHandler(): framework-agnostic (Fetch Request in, identity out)
- * - expressAgentAuth():        Express / Connect middleware
- * - agentronicsMiddleware():   Next.js middleware — see '@agentronics/sdk/next'
+ *   // app/.well-known/agent-context.json/route.ts (Next.js)
+ *   export const GET = createAgentContextHandler({ sync })
  *
- * 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.
+ * The snapshot comes from `sync.pullConfig()` (the last `pushMemory()` for this
+ * site), cached in memory. If the console can't be reached, the last good
+ * snapshot keeps being served; with none, the route answers 404.
  */
 
-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;
+interface AgentContextHandlerOptions {
+    sync: Pick<IntelSync, 'pullConfig'>;
+    /** How long to reuse a snapshot. Default 300 s. */
+    cacheSeconds?: number;
 }
-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;
+declare function createAgentContextHandler({ sync, cacheSeconds }: AgentContextHandlerOptions): () => Promise<Response>;
 
-export { AGENT_HEADERS, type AgentAuthHandlerOptions, type AgentAuthMethod, type AgentAuthOptions, type AgentAuthResult, type ApiKeyIdentity, type ApiKeyOptions, type ClientIpSource, type CrawlerOptions, DIRECTORY_PATH, type HandlerOutcome, type OAuth2Options, type PublicJwk, RDNS_DOMAINS, type ReplayCache, type SignatureAlgorithm, type VerifiedAgent, WEB_BOT_AUTH_TAG, type WebBotAuthOptions, type WebBotAuthResult, classifyUserAgent, clientIp, createAgentAuth, createAgentAuthHandler, expressAgentAuth, generateAgentKey, hashAgentKey, jwkThumbprint, memoryReplayCache, readAgentHeaders, signatureBase, staticKeyVerifier, toTraceEvent, verifyCrawler, verifyWebBotAuth, withAgentHeaders };
+export { type AgentContextHandlerOptions, type TraceRelayOptions, createAgentContextHandler, createTraceRelay };