@kya-os/checkpoint-nextjs 1.0.0

package/dist/adapt.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapt.ts"],"names":["acceptsHtml","encodeVerdictCookie","classifyResponseShape","NextResponse","BLOCKED_PATH","VERDICT_COOKIE_NAME"],"mappings":";;;;;;AA4CO,SAAS,mBAAA,CAAoB,UAA4B,GAAA,EAAgC;AAC9F,EAAA,MAAM,iBAAA,GAAoBA,4BAAA,CAAY,GAAA,CAAI,OAAO,CAAA;AACjD,EAAA,MAAM,aAAA,GAAgBC,qCAAoB,QAAQ,CAAA;AAClD,EAAA,MAAM,KAAA,GAAQC,sCAAA,CAAsB,QAAA,EAAU,iBAAiB,CAAA;AAE/D,EAAA,QAAQ,KAAA;AAAO,IACb,KAAK,cAAA,EAAgB;AAEnB,MAAA,MAAM,GAAA,GAAMC,oBAAa,IAAA,EAAK;AAC9B,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,UAAA,EAAY;AAEf,MAAA,MAAM,MAAA,GAAS,IAAI,GAAA,CAAI,QAAA,CAAS,QAAQ,QAAS,CAAA;AACjD,MAAA,MAAM,GAAA,GAAMA,mBAAA,CAAa,QAAA,CAAS,MAAM,CAAA;AACxC,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,YAAA,EAAc;AAIjB,MAAA,MAAM,UAAA,GAAa,IAAI,GAAA,CAAIC,6BAAA,EAAc,IAAI,GAAG,CAAA;AAChD,MAAA,MAAM,MAAMD,mBAAA,CAAa,OAAA,CAAQ,YAAY,EAAE,MAAA,EAAQ,KAAK,CAAA;AAC5D,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,YAAA,EAAc;AAKjB,MAAA,MAAM,IAAA,GAAO,QAAA,CAAS,IAAA,IAAQ,EAAC;AAC/B,MAAA,MAAM,GAAA,GAAMA,oBAAa,IAAA,CAAK,IAAA,EAAM,EAAE,MAAA,EAAQ,QAAA,CAAS,QAAkB,CAAA;AACzE,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA;AAEJ;AAUA,SAAS,gBAAA,CAAiB,KAAmB,KAAA,EAAqB;AAKhE,EAAA,GAAA,CAAI,QAAQ,GAAA,CAAI;AAAA,IACd,IAAA,EAAME,oCAAA;AAAA,IACN,KAAA;AAAA,IACA,IAAA,EAAM,GAAA;AAAA,IACN,QAAA,EAAU,KAAA;AAAA,IACV,QAAA,EAAU;AAAA,GACX,CAAA;AACH;AAEA,SAAS,YAAA,CAAa,KAAmB,OAAA,EAAuC;AAI9E,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,OAAO,CAAA,EAAG;AAClD,IAAA,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,GAAA,EAAK,KAAK,CAAA;AAAA,EAC5B;AACF","file":"adapt.js","sourcesContent":["/**\n * D.3 — `RenderedResponse` → `NextResponse` adapter.\n *\n * The host wrapper's *only* job on the outbound path: take the\n * transport-agnostic `RenderedResponse` Phase C's\n * `renderDecisionAsResponse` produces and translate it to a\n * `NextResponse`. Zero verdict decisions, zero engine I/O.\n *\n * Shared between the Node-runtime and Edge-runtime entries. The\n * branching here is identical in both — Next.js `NextResponse` has the\n * same API surface across runtimes; only the underlying response\n * primitive differs (Node http.ServerResponse vs Edge `Response`).\n *\n * Architectural pins per architect § 4.3 / § 4.4:\n *\n *   1. **Verdict-cookie format is contract.** Sites-1's Sonner toast\n *      depends on `__checkpoint_verdict=%7B%22verdict%22%3A%22<v>%22...\n *      %7D` (single URL-encoded JSON). Byte-format pinned by adapt.test.\n *\n *   2. **HTML-accepting clients → `/blocked` rewrite at status 200**\n *      (so the page renders with the verdict cookie set; Sonner picks\n *      up the cookie and shows the toast). Non-HTML clients → JSON 4xx.\n *\n *   3. **`X-Checkpoint-Engine` carries `result.engineInfo.name`** —\n *      `checkpoint-engine-wasm` after Phase D ships. Brian's Sites-2\n *      deviation note confirmed the `X-Checkpoint-*` prefix is canon.\n */\n\nimport { type NextRequest, NextResponse } from 'next/server';\n\nimport type { RenderedResponse } from '@kya-os/checkpoint-wasm-runtime/orchestrator';\nimport {\n  VERDICT_COOKIE_NAME,\n  BLOCKED_PATH,\n  encodeVerdictCookie,\n  acceptsHtml,\n  classifyResponseShape,\n} from '@kya-os/checkpoint-shared';\n\n/**\n * Convert the engine's transport-agnostic `RenderedResponse` into a\n * `NextResponse`. Sites-1's Playwright suite is the regression gate;\n * any drift here is caught downstream.\n */\nexport function adaptToNextResponse(rendered: RenderedResponse, req: NextRequest): NextResponse {\n  const clientAcceptsHtml = acceptsHtml(req.headers);\n  const verdictCookie = encodeVerdictCookie(rendered);\n  const shape = classifyResponseShape(rendered, clientAcceptsHtml);\n\n  switch (shape) {\n    case 'pass-through': {\n      // Permit OR Observe-mode any-verdict.\n      const res = NextResponse.next();\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'redirect': {\n      // Decision::Redirect → 302 + Location.\n      const target = new URL(rendered.headers.Location!);\n      const res = NextResponse.redirect(target);\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'html-block': {\n      // Sites-1 contract: HTML clients (browsers) need a renderable page\n      // to show the rejection UI. The verdict cookie carries the reason;\n      // the /blocked route reads it and renders the toast.\n      const blockedUrl = new URL(BLOCKED_PATH, req.url);\n      const res = NextResponse.rewrite(blockedUrl, { status: 200 });\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'json-block': {\n      // The orchestrator's RenderedResponse already supplies the correct\n      // status (401/403/422/...); we just need to materialise the body.\n      // application/problem+json (Instruct) uses the Content-Type from\n      // rendered.headers; defaults to application/json for everything else.\n      const body = rendered.body ?? {};\n      const res = NextResponse.json(body, { status: rendered.status as number });\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n  }\n}\n\n// -----------------------------------------------------------------------------\n// Helpers — Next.js-specific glue. The framework-agnostic primitives\n// (encodeVerdictCookie, acceptsHtml, classifyResponseShape,\n// VERDICT_COOKIE_NAME, BLOCKED_PATH) live in `@kya-os/checkpoint-shared`\n// so checkpoint-express + future host wrappers produce byte-identical\n// cookies and route HTML/JSON branching the same way.\n// -----------------------------------------------------------------------------\n\nfunction setVerdictCookie(res: NextResponse, value: string): void {\n  // Path / SameSite / HttpOnly chosen for the Sonner-bridge use case:\n  // path=/ so any route can read it, SameSite=Lax so first-party\n  // navigations carry it, HttpOnly=false so the client-side toast JS\n  // can read it (it's verdict UX, not a session token).\n  res.cookies.set({\n    name: VERDICT_COOKIE_NAME,\n    value,\n    path: '/',\n    sameSite: 'lax',\n    httpOnly: false,\n  });\n}\n\nfunction applyHeaders(res: NextResponse, headers: Record<string, string>): void {\n  // NextResponse.next() / rewrite() / json() return responses with\n  // some default headers; orchestrator headers (X-Checkpoint-*, Location)\n  // override. We don't strip pre-existing headers — only set new ones.\n  for (const [key, value] of Object.entries(headers)) {\n    res.headers.set(key, value);\n  }\n}\n"]}

package/dist/adapt.mjs

@@ -0,0 +1,56 @@
+import { NextResponse } from 'next/server';
+import { acceptsHtml, encodeVerdictCookie, classifyResponseShape, BLOCKED_PATH, VERDICT_COOKIE_NAME } from '@kya-os/checkpoint-shared';
+
+// src/adapt.ts
+function adaptToNextResponse(rendered, req) {
+  const clientAcceptsHtml = acceptsHtml(req.headers);
+  const verdictCookie = encodeVerdictCookie(rendered);
+  const shape = classifyResponseShape(rendered, clientAcceptsHtml);
+  switch (shape) {
+    case "pass-through": {
+      const res = NextResponse.next();
+      applyHeaders(res, rendered.headers);
+      setVerdictCookie(res, verdictCookie);
+      return res;
+    }
+    case "redirect": {
+      const target = new URL(rendered.headers.Location);
+      const res = NextResponse.redirect(target);
+      applyHeaders(res, rendered.headers);
+      setVerdictCookie(res, verdictCookie);
+      return res;
+    }
+    case "html-block": {
+      const blockedUrl = new URL(BLOCKED_PATH, req.url);
+      const res = NextResponse.rewrite(blockedUrl, { status: 200 });
+      applyHeaders(res, rendered.headers);
+      setVerdictCookie(res, verdictCookie);
+      return res;
+    }
+    case "json-block": {
+      const body = rendered.body ?? {};
+      const res = NextResponse.json(body, { status: rendered.status });
+      applyHeaders(res, rendered.headers);
+      setVerdictCookie(res, verdictCookie);
+      return res;
+    }
+  }
+}
+function setVerdictCookie(res, value) {
+  res.cookies.set({
+    name: VERDICT_COOKIE_NAME,
+    value,
+    path: "/",
+    sameSite: "lax",
+    httpOnly: false
+  });
+}
+function applyHeaders(res, headers) {
+  for (const [key, value] of Object.entries(headers)) {
+    res.headers.set(key, value);
+  }
+}
+
+export { adaptToNextResponse };
+//# sourceMappingURL=adapt.mjs.map
+//# sourceMappingURL=adapt.mjs.map

package/dist/adapt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapt.ts"],"names":[],"mappings":";;;;AA4CO,SAAS,mBAAA,CAAoB,UAA4B,GAAA,EAAgC;AAC9F,EAAA,MAAM,iBAAA,GAAoB,WAAA,CAAY,GAAA,CAAI,OAAO,CAAA;AACjD,EAAA,MAAM,aAAA,GAAgB,oBAAoB,QAAQ,CAAA;AAClD,EAAA,MAAM,KAAA,GAAQ,qBAAA,CAAsB,QAAA,EAAU,iBAAiB,CAAA;AAE/D,EAAA,QAAQ,KAAA;AAAO,IACb,KAAK,cAAA,EAAgB;AAEnB,MAAA,MAAM,GAAA,GAAM,aAAa,IAAA,EAAK;AAC9B,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,UAAA,EAAY;AAEf,MAAA,MAAM,MAAA,GAAS,IAAI,GAAA,CAAI,QAAA,CAAS,QAAQ,QAAS,CAAA;AACjD,MAAA,MAAM,GAAA,GAAM,YAAA,CAAa,QAAA,CAAS,MAAM,CAAA;AACxC,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,YAAA,EAAc;AAIjB,MAAA,MAAM,UAAA,GAAa,IAAI,GAAA,CAAI,YAAA,EAAc,IAAI,GAAG,CAAA;AAChD,MAAA,MAAM,MAAM,YAAA,CAAa,OAAA,CAAQ,YAAY,EAAE,MAAA,EAAQ,KAAK,CAAA;AAC5D,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,IAEA,KAAK,YAAA,EAAc;AAKjB,MAAA,MAAM,IAAA,GAAO,QAAA,CAAS,IAAA,IAAQ,EAAC;AAC/B,MAAA,MAAM,GAAA,GAAM,aAAa,IAAA,CAAK,IAAA,EAAM,EAAE,MAAA,EAAQ,QAAA,CAAS,QAAkB,CAAA;AACzE,MAAA,YAAA,CAAa,GAAA,EAAK,SAAS,OAAO,CAAA;AAClC,MAAA,gBAAA,CAAiB,KAAK,aAAa,CAAA;AACnC,MAAA,OAAO,GAAA;AAAA,IACT;AAAA;AAEJ;AAUA,SAAS,gBAAA,CAAiB,KAAmB,KAAA,EAAqB;AAKhE,EAAA,GAAA,CAAI,QAAQ,GAAA,CAAI;AAAA,IACd,IAAA,EAAM,mBAAA;AAAA,IACN,KAAA;AAAA,IACA,IAAA,EAAM,GAAA;AAAA,IACN,QAAA,EAAU,KAAA;AAAA,IACV,QAAA,EAAU;AAAA,GACX,CAAA;AACH;AAEA,SAAS,YAAA,CAAa,KAAmB,OAAA,EAAuC;AAI9E,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,OAAO,CAAA,EAAG;AAClD,IAAA,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,GAAA,EAAK,KAAK,CAAA;AAAA,EAC5B;AACF","file":"adapt.mjs","sourcesContent":["/**\n * D.3 — `RenderedResponse` → `NextResponse` adapter.\n *\n * The host wrapper's *only* job on the outbound path: take the\n * transport-agnostic `RenderedResponse` Phase C's\n * `renderDecisionAsResponse` produces and translate it to a\n * `NextResponse`. Zero verdict decisions, zero engine I/O.\n *\n * Shared between the Node-runtime and Edge-runtime entries. The\n * branching here is identical in both — Next.js `NextResponse` has the\n * same API surface across runtimes; only the underlying response\n * primitive differs (Node http.ServerResponse vs Edge `Response`).\n *\n * Architectural pins per architect § 4.3 / § 4.4:\n *\n *   1. **Verdict-cookie format is contract.** Sites-1's Sonner toast\n *      depends on `__checkpoint_verdict=%7B%22verdict%22%3A%22<v>%22...\n *      %7D` (single URL-encoded JSON). Byte-format pinned by adapt.test.\n *\n *   2. **HTML-accepting clients → `/blocked` rewrite at status 200**\n *      (so the page renders with the verdict cookie set; Sonner picks\n *      up the cookie and shows the toast). Non-HTML clients → JSON 4xx.\n *\n *   3. **`X-Checkpoint-Engine` carries `result.engineInfo.name`** —\n *      `checkpoint-engine-wasm` after Phase D ships. Brian's Sites-2\n *      deviation note confirmed the `X-Checkpoint-*` prefix is canon.\n */\n\nimport { type NextRequest, NextResponse } from 'next/server';\n\nimport type { RenderedResponse } from '@kya-os/checkpoint-wasm-runtime/orchestrator';\nimport {\n  VERDICT_COOKIE_NAME,\n  BLOCKED_PATH,\n  encodeVerdictCookie,\n  acceptsHtml,\n  classifyResponseShape,\n} from '@kya-os/checkpoint-shared';\n\n/**\n * Convert the engine's transport-agnostic `RenderedResponse` into a\n * `NextResponse`. Sites-1's Playwright suite is the regression gate;\n * any drift here is caught downstream.\n */\nexport function adaptToNextResponse(rendered: RenderedResponse, req: NextRequest): NextResponse {\n  const clientAcceptsHtml = acceptsHtml(req.headers);\n  const verdictCookie = encodeVerdictCookie(rendered);\n  const shape = classifyResponseShape(rendered, clientAcceptsHtml);\n\n  switch (shape) {\n    case 'pass-through': {\n      // Permit OR Observe-mode any-verdict.\n      const res = NextResponse.next();\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'redirect': {\n      // Decision::Redirect → 302 + Location.\n      const target = new URL(rendered.headers.Location!);\n      const res = NextResponse.redirect(target);\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'html-block': {\n      // Sites-1 contract: HTML clients (browsers) need a renderable page\n      // to show the rejection UI. The verdict cookie carries the reason;\n      // the /blocked route reads it and renders the toast.\n      const blockedUrl = new URL(BLOCKED_PATH, req.url);\n      const res = NextResponse.rewrite(blockedUrl, { status: 200 });\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n\n    case 'json-block': {\n      // The orchestrator's RenderedResponse already supplies the correct\n      // status (401/403/422/...); we just need to materialise the body.\n      // application/problem+json (Instruct) uses the Content-Type from\n      // rendered.headers; defaults to application/json for everything else.\n      const body = rendered.body ?? {};\n      const res = NextResponse.json(body, { status: rendered.status as number });\n      applyHeaders(res, rendered.headers);\n      setVerdictCookie(res, verdictCookie);\n      return res;\n    }\n  }\n}\n\n// -----------------------------------------------------------------------------\n// Helpers — Next.js-specific glue. The framework-agnostic primitives\n// (encodeVerdictCookie, acceptsHtml, classifyResponseShape,\n// VERDICT_COOKIE_NAME, BLOCKED_PATH) live in `@kya-os/checkpoint-shared`\n// so checkpoint-express + future host wrappers produce byte-identical\n// cookies and route HTML/JSON branching the same way.\n// -----------------------------------------------------------------------------\n\nfunction setVerdictCookie(res: NextResponse, value: string): void {\n  // Path / SameSite / HttpOnly chosen for the Sonner-bridge use case:\n  // path=/ so any route can read it, SameSite=Lax so first-party\n  // navigations carry it, HttpOnly=false so the client-side toast JS\n  // can read it (it's verdict UX, not a session token).\n  res.cookies.set({\n    name: VERDICT_COOKIE_NAME,\n    value,\n    path: '/',\n    sameSite: 'lax',\n    httpOnly: false,\n  });\n}\n\nfunction applyHeaders(res: NextResponse, headers: Record<string, string>): void {\n  // NextResponse.next() / rewrite() / json() return responses with\n  // some default headers; orchestrator headers (X-Checkpoint-*, Location)\n  // override. We don't strip pre-existing headers — only set new ones.\n  for (const [key, value] of Object.entries(headers)) {\n    res.headers.set(key, value);\n  }\n}\n"]}

package/dist/api-client.d.mts

@@ -0,0 +1,204 @@
+import { EnforcementAction } from '@kya-os/checkpoint-shared';
+export { EnforcementAction } from '@kya-os/checkpoint-shared';
+
+/**
+ * AgentShield API Client
+ *
+ * Lightweight client for calling the AgentShield enforce API from middleware.
+ * Designed for Edge Runtime compatibility (no Node.js-specific APIs).
+ */
+
+/**
+ * API client configuration
+ */
+interface CheckpointApiClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** API base URL (defaults to production) */
+    baseUrl?: string;
+    /**
+     * Use edge detection for lower latency (~30-50ms vs ~150ms) and better coverage.
+     * Edge detection can identify non-JS clients (curl, Python, Claude Code WebFetch)
+     * that the pixel cannot detect since they don't execute JavaScript.
+     * @default true
+     */
+    useEdge?: boolean;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Enforcement decision from the API
+ */
+interface EnforcementDecision {
+    action: EnforcementAction;
+    reason: string;
+    isAgent: boolean;
+    confidence: number;
+    agentName?: string;
+    agentType?: string;
+    redirectUrl?: string;
+    message?: string;
+    metadata?: {
+        policyVersion?: string;
+        signatureVerified?: boolean;
+        denyListMatch?: {
+            clientDid?: string;
+            agentDid?: string;
+            clientName?: string;
+            reason?: string;
+        };
+    };
+}
+/**
+ * Detection result (optional in response)
+ */
+interface DetectionResult {
+    isAgent: boolean;
+    confidence: number;
+    agentName?: string;
+    agentType?: string;
+    /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */
+    detectionClass?: string;
+    verificationMethod?: string;
+    reasons?: string[];
+    /** Detection engine used: 'wasm' or 'javascript-fallback' */
+    detectionMethod?: string;
+}
+/**
+ * Enforce API response
+ */
+interface EnforceResponse {
+    success: boolean;
+    data?: {
+        decision: EnforcementDecision;
+        processingTimeMs: number;
+        requestId: string;
+        detection?: DetectionResult;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Request input for enforce API
+ */
+interface EnforceInput {
+    /** HTTP headers from the incoming request */
+    headers?: Record<string, string>;
+    /** User-Agent header */
+    userAgent?: string;
+    /** Client IP address */
+    ipAddress?: string;
+    /** Request path */
+    path?: string;
+    /** Request URL */
+    url?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Options */
+    options?: {
+        /** Include full detection result */
+        includeDetectionResult?: boolean;
+        /** Cache TTL override */
+        cacheTTL?: number;
+    };
+}
+/**
+ * Input for logging a detection result
+ */
+interface LogDetectionInput {
+    /** Detection result from Gateway */
+    detection: DetectionResult;
+    /** Request context */
+    context: {
+        userAgent?: string;
+        ipAddress?: string;
+        path?: string;
+        url?: string;
+        method?: string;
+    };
+    /** Source of the detection */
+    source?: 'gateway' | 'middleware';
+}
+/**
+ * AgentShield API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new CheckpointApiClient({
+ *   apiKey: process.env.CHECKPOINT_API_KEY!,
+ * });
+ *
+ * const result = await client.enforce({
+ *   headers: Object.fromEntries(request.headers),
+ *   path: request.nextUrl.pathname,
+ *   method: request.method,
+ * });
+ *
+ * if (result.decision.action === 'block') {
+ *   return new Response('Access denied', { status: 403 });
+ * }
+ * ```
+ */
+declare class CheckpointApiClient {
+    private apiKey;
+    private baseUrl;
+    private useEdge;
+    private timeout;
+    private debug;
+    constructor(config: CheckpointApiClientConfig);
+    /**
+     * Call the enforce API to check if a request should be allowed
+     */
+    enforce(input: EnforceInput): Promise<EnforceResponse>;
+    /**
+     * Quick check - returns just the action without full response parsing
+     * Useful for very fast middleware that just needs allow/block
+     */
+    quickCheck(input: EnforceInput): Promise<{
+        action: EnforcementAction;
+        error?: string;
+    }>;
+    /**
+     * Check if this client is using edge detection (Gateway Worker)
+     */
+    isUsingEdge(): boolean;
+    /**
+     * Log a detection result to AgentShield database.
+     * Use after Gateway Worker detection to persist results.
+     * Fire-and-forget - returns immediately without waiting for DB write.
+     *
+     * @example
+     * ```typescript
+     * // After receiving Gateway response
+     * if (client.isUsingEdge() && response.data?.detection) {
+     *   client.logDetection({
+     *     detection: response.data.detection,
+     *     context: { userAgent, ipAddress, path, url, method }
+     *   }).catch(err => console.error('Log failed:', err));
+     * }
+     * ```
+     */
+    logDetection(input: LogDetectionInput): Promise<void>;
+}
+declare function getCheckpointApiClient(config?: Partial<CheckpointApiClientConfig>): CheckpointApiClient;
+/**
+ * Reset the singleton client (useful for testing)
+ */
+declare function resetCheckpointApiClient(): void;
+/** @deprecated Renamed to {@link CheckpointApiClient}. The runtime is identical. */
+declare const AgentShieldClient: typeof CheckpointApiClient;
+/** @deprecated Renamed to {@link CheckpointApiClientConfig}. */
+type AgentShieldClientConfig = CheckpointApiClientConfig;
+/** @deprecated Renamed to {@link getCheckpointApiClient}. */
+declare const getAgentShieldClient: typeof getCheckpointApiClient;
+/** @deprecated Renamed to {@link resetCheckpointApiClient}. */
+declare const resetAgentShieldClient: typeof resetCheckpointApiClient;
+
+export { AgentShieldClient, type AgentShieldClientConfig, CheckpointApiClient, type CheckpointApiClientConfig, type DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };

package/dist/api-client.d.ts

@@ -0,0 +1,204 @@
+import { EnforcementAction } from '@kya-os/checkpoint-shared';
+export { EnforcementAction } from '@kya-os/checkpoint-shared';
+
+/**
+ * AgentShield API Client
+ *
+ * Lightweight client for calling the AgentShield enforce API from middleware.
+ * Designed for Edge Runtime compatibility (no Node.js-specific APIs).
+ */
+
+/**
+ * API client configuration
+ */
+interface CheckpointApiClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** API base URL (defaults to production) */
+    baseUrl?: string;
+    /**
+     * Use edge detection for lower latency (~30-50ms vs ~150ms) and better coverage.
+     * Edge detection can identify non-JS clients (curl, Python, Claude Code WebFetch)
+     * that the pixel cannot detect since they don't execute JavaScript.
+     * @default true
+     */
+    useEdge?: boolean;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Enforcement decision from the API
+ */
+interface EnforcementDecision {
+    action: EnforcementAction;
+    reason: string;
+    isAgent: boolean;
+    confidence: number;
+    agentName?: string;
+    agentType?: string;
+    redirectUrl?: string;
+    message?: string;
+    metadata?: {
+        policyVersion?: string;
+        signatureVerified?: boolean;
+        denyListMatch?: {
+            clientDid?: string;
+            agentDid?: string;
+            clientName?: string;
+            reason?: string;
+        };
+    };
+}
+/**
+ * Detection result (optional in response)
+ */
+interface DetectionResult {
+    isAgent: boolean;
+    confidence: number;
+    agentName?: string;
+    agentType?: string;
+    /** Detection class: 'human', 'ai_agent', 'bot', 'incomplete_data' */
+    detectionClass?: string;
+    verificationMethod?: string;
+    reasons?: string[];
+    /** Detection engine used: 'wasm' or 'javascript-fallback' */
+    detectionMethod?: string;
+}
+/**
+ * Enforce API response
+ */
+interface EnforceResponse {
+    success: boolean;
+    data?: {
+        decision: EnforcementDecision;
+        processingTimeMs: number;
+        requestId: string;
+        detection?: DetectionResult;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Request input for enforce API
+ */
+interface EnforceInput {
+    /** HTTP headers from the incoming request */
+    headers?: Record<string, string>;
+    /** User-Agent header */
+    userAgent?: string;
+    /** Client IP address */
+    ipAddress?: string;
+    /** Request path */
+    path?: string;
+    /** Request URL */
+    url?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Options */
+    options?: {
+        /** Include full detection result */
+        includeDetectionResult?: boolean;
+        /** Cache TTL override */
+        cacheTTL?: number;
+    };
+}
+/**
+ * Input for logging a detection result
+ */
+interface LogDetectionInput {
+    /** Detection result from Gateway */
+    detection: DetectionResult;
+    /** Request context */
+    context: {
+        userAgent?: string;
+        ipAddress?: string;
+        path?: string;
+        url?: string;
+        method?: string;
+    };
+    /** Source of the detection */
+    source?: 'gateway' | 'middleware';
+}
+/**
+ * AgentShield API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new CheckpointApiClient({
+ *   apiKey: process.env.CHECKPOINT_API_KEY!,
+ * });
+ *
+ * const result = await client.enforce({
+ *   headers: Object.fromEntries(request.headers),
+ *   path: request.nextUrl.pathname,
+ *   method: request.method,
+ * });
+ *
+ * if (result.decision.action === 'block') {
+ *   return new Response('Access denied', { status: 403 });
+ * }
+ * ```
+ */
+declare class CheckpointApiClient {
+    private apiKey;
+    private baseUrl;
+    private useEdge;
+    private timeout;
+    private debug;
+    constructor(config: CheckpointApiClientConfig);
+    /**
+     * Call the enforce API to check if a request should be allowed
+     */
+    enforce(input: EnforceInput): Promise<EnforceResponse>;
+    /**
+     * Quick check - returns just the action without full response parsing
+     * Useful for very fast middleware that just needs allow/block
+     */
+    quickCheck(input: EnforceInput): Promise<{
+        action: EnforcementAction;
+        error?: string;
+    }>;
+    /**
+     * Check if this client is using edge detection (Gateway Worker)
+     */
+    isUsingEdge(): boolean;
+    /**
+     * Log a detection result to AgentShield database.
+     * Use after Gateway Worker detection to persist results.
+     * Fire-and-forget - returns immediately without waiting for DB write.
+     *
+     * @example
+     * ```typescript
+     * // After receiving Gateway response
+     * if (client.isUsingEdge() && response.data?.detection) {
+     *   client.logDetection({
+     *     detection: response.data.detection,
+     *     context: { userAgent, ipAddress, path, url, method }
+     *   }).catch(err => console.error('Log failed:', err));
+     * }
+     * ```
+     */
+    logDetection(input: LogDetectionInput): Promise<void>;
+}
+declare function getCheckpointApiClient(config?: Partial<CheckpointApiClientConfig>): CheckpointApiClient;
+/**
+ * Reset the singleton client (useful for testing)
+ */
+declare function resetCheckpointApiClient(): void;
+/** @deprecated Renamed to {@link CheckpointApiClient}. The runtime is identical. */
+declare const AgentShieldClient: typeof CheckpointApiClient;
+/** @deprecated Renamed to {@link CheckpointApiClientConfig}. */
+type AgentShieldClientConfig = CheckpointApiClientConfig;
+/** @deprecated Renamed to {@link getCheckpointApiClient}. */
+declare const getAgentShieldClient: typeof getCheckpointApiClient;
+/** @deprecated Renamed to {@link resetCheckpointApiClient}. */
+declare const resetAgentShieldClient: typeof resetCheckpointApiClient;
+
+export { AgentShieldClient, type AgentShieldClientConfig, CheckpointApiClient, type CheckpointApiClientConfig, type DetectionResult, type EnforceInput, type EnforceResponse, type EnforcementDecision, type LogDetectionInput, getAgentShieldClient, getCheckpointApiClient, resetAgentShieldClient, resetCheckpointApiClient };