@kya-os/checkpoint-nextjs 1.0.0

package/templates/middleware-wasm-100.ts

@@ -0,0 +1,153 @@
+/**
+ * AgentShield Middleware Template with WASM (95-100% Confidence)
+ *
+ * This template provides full cryptographic verification for AI agents
+ * following Next.js official documentation for WebAssembly in Edge Runtime.
+ *
+ * Installation:
+ * 1. Copy this file to your project root as `middleware.ts`
+ * 2. Install packages: npm install @kya-os/checkpoint @kya-os/checkpoint-nextjs
+ * 3. Deploy to Vercel for Edge Runtime support
+ */
+
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+// CRITICAL: Import WASM module with ?module suffix for Edge Runtime
+// This MUST be at the top of the file, before any other AgentShield imports
+import wasmModule from '@kya-os/checkpoint/wasm?module';
+
+// Now import the middleware creator
+import {
+  createWasmAgentShieldMiddleware,
+  instantiateWasm,
+} from '@kya-os/checkpoint-nextjs/wasm-middleware';
+
+// Initialize WASM module once at startup
+let wasmInstancePromise: Promise<WebAssembly.Instance> | null = null;
+
+async function getWasmInstance() {
+  if (!wasmInstancePromise) {
+    wasmInstancePromise = instantiateWasm(wasmModule);
+  }
+  return wasmInstancePromise;
+}
+
+export async function middleware(request: NextRequest) {
+  try {
+    // Get or create WASM instance
+    const wasmInstance = await getWasmInstance();
+
+    // Create middleware with WASM support
+    const agentShieldMiddleware = createWasmAgentShieldMiddleware({
+      wasmInstance,
+
+      // Skip authentication and static assets
+      skipPaths: ['/api/auth', '/_next', '/favicon.ico', '/public'],
+
+      // What to do when agent is detected
+      onAgentDetected: async (result) => {
+        // With WASM: 95-100% confidence for cryptographically verified agents
+        console.log(`🤖 AI Agent detected:`, {
+          agent: result.agent,
+          confidence: `${Math.round(result.confidence * 100)}%`,
+          verification: result.verificationMethod, // 'signature' with WASM, 'pattern' without
+          risk: result.riskLevel,
+          timestamp: result.timestamp,
+        });
+
+        // You can add custom logic here:
+        // - Log to analytics
+        // - Send alerts
+        // - Apply rate limiting
+        // - etc.
+      },
+
+      // Set to true to block AI agents
+      blockOnHighConfidence: false, // Change to true to block agents
+
+      // Minimum confidence to trigger blocking (0.8 = 80%)
+      confidenceThreshold: 0.8,
+
+      // Custom response when blocking
+      blockedResponse: {
+        status: 403,
+        message: 'AI agent access restricted',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Blocked-Reason': 'ai-agent-detected',
+        },
+      },
+    });
+
+    // Run AgentShield detection
+    const response = await agentShieldMiddleware(request);
+
+    // Add security headers to all responses
+    response.headers.set('X-Frame-Options', 'DENY');
+    response.headers.set('X-Content-Type-Options', 'nosniff');
+    response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+
+    return response;
+  } catch (error) {
+    // If WASM fails to load, fall back to pattern detection (85% confidence)
+    console.warn('⚠️ WASM initialization failed, using pattern detection:', error);
+
+    // You could use the regular middleware here as fallback
+    // For now, just continue
+    return NextResponse.next();
+  }
+}
+
+// Configure which paths the middleware runs on
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     * - public folder
+     */
+    {
+      source: '/((?!_next/static|_next/image|favicon.ico|public).*)',
+      missing: [
+        { type: 'header', key: 'next-router-prefetch' },
+        { type: 'header', key: 'purpose', value: 'prefetch' },
+      ],
+    },
+  ],
+};
+
+/**
+ * TypeScript Support
+ *
+ * Add this to a `types/wasm.d.ts` file in your project:
+ *
+ * declare module '@kya-os/checkpoint/wasm?module' {
+ *   const value: WebAssembly.Module;
+ *   export default value;
+ * }
+ */
+
+/**
+ * What You'll See in Logs:
+ *
+ * With WASM (95-100% confidence):
+ * 🤖 AI Agent detected: {
+ *   agent: 'ChatGPT-User',
+ *   confidence: '100%',
+ *   verification: 'signature',  // Cryptographically verified!
+ *   risk: 'high',
+ *   timestamp: '2024-01-01T00:00:00.000Z'
+ * }
+ *
+ * Without WASM (85% confidence):
+ * 🤖 AI Agent detected: {
+ *   agent: 'ChatGPT-User',
+ *   confidence: '85%',
+ *   verification: 'pattern',    // Pattern matching only
+ *   risk: 'medium',
+ *   timestamp: '2024-01-01T00:00:00.000Z'
+ * }
+ */

package/wasm/agentshield_wasm.d.ts

@@ -0,0 +1,479 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Initialize the AgentShield WASM module
+ */
+export function init(): void;
+/**
+ * Analyze a request and detect if it's from an agent
+ */
+export function detect_agent(metadata: JsRequestMetadata): JsDetectionResult;
+/**
+ * Get the version of the AgentShield library
+ */
+export function version(): string;
+/**
+ * Get the version of the AgentShield library
+ */
+export function get_version(): string;
+/**
+ * Get build information
+ */
+export function get_build_info(): string;
+/**
+ * Verify an MCP-I proof (VC-JWT token)
+ *
+ * This function verifies a Verifiable Credential JWT and extracts the
+ * principal (issuer) and agent (subject) DIDs.
+ *
+ * # Arguments
+ *
+ * * `vc_jwt` - The VC-JWT token string (header.payload.signature)
+ * * `current_time_secs` - Current Unix timestamp in seconds (for expiration check)
+ *
+ * # Returns
+ *
+ * A `JsMcpIVerificationResult` with verification status and extracted DIDs.
+ */
+export function verify_mcp_i_proof(
+  vc_jwt: string,
+  current_time_secs: bigint
+): JsMcpIVerificationResult;
+/**
+ * Resolve a did:key identifier to its public key
+ *
+ * # Arguments
+ *
+ * * `did` - The did:key identifier (e.g., "did:key:z6Mkf...")
+ *
+ * # Returns
+ *
+ * A `JsDidKeyResult` with the resolved public key or an error.
+ */
+export function resolve_did_key_wasm(did: string): JsDidKeyResult;
+/**
+ * Check if a requested scope is permitted by granted scopes
+ *
+ * # Arguments
+ *
+ * * `requested` - The scope being requested (e.g., "read:email")
+ * * `granted_json` - JSON array of granted scopes (e.g., "[\"read:*\", \"write:calendar\"]")
+ *
+ * # Returns
+ *
+ * A `JsScopeCheckResult` indicating whether the scope is permitted.
+ */
+export function check_delegation_scope(requested: string, granted_json: string): JsScopeCheckResult;
+/**
+ * Verify a delegation with time constraints
+ *
+ * # Arguments
+ *
+ * * `requested` - The scope being requested
+ * * `granted_json` - JSON array of granted scopes
+ * * `not_before` - Optional Unix timestamp (0 to skip)
+ * * `not_after` - Optional Unix timestamp (0 to skip)
+ * * `current_time` - Current Unix timestamp (0 to skip time checks)
+ *
+ * # Returns
+ *
+ * A `JsScopeCheckResult` indicating whether the delegation is valid.
+ */
+export function verify_delegation_scope(
+  requested: string,
+  granted_json: string,
+  not_before: bigint,
+  not_after: bigint,
+  current_time: bigint
+): JsScopeCheckResult;
+/**
+ * Evaluate a request against a policy configuration
+ *
+ * # Arguments
+ *
+ * * `policy_json` - Policy configuration as JSON string
+ * * `context_json` - Evaluation context as JSON string
+ *
+ * # Returns
+ *
+ * A `JsPolicyEvaluationResult` with the enforcement action and reason.
+ *
+ * # Example
+ *
+ * ```javascript
+ * const policy = JSON.stringify({
+ *   version: "1.0.0",
+ *   enabled: true,
+ *   defaultAction: "allow",
+ *   thresholds: { confidenceThreshold: 80, confidenceAction: "block" },
+ *   denyList: [],
+ *   allowList: [],
+ *   rules: []
+ * });
+ *
+ * const context = JSON.stringify({
+ *   agentType: "ai_agent",
+ *   agentName: "ChatGPT",
+ *   confidence: 95
+ * });
+ *
+ * const result = evaluate_policy(policy, context);
+ * console.log(result.action); // "block" (confidence exceeded threshold)
+ * ```
+ */
+export function evaluate_policy(
+  policy_json: string,
+  context_json: string
+): JsPolicyEvaluationResult;
+/**
+ * Check if a policy allows a request (convenience function)
+ *
+ * # Arguments
+ *
+ * * `policy_json` - Policy configuration as JSON string
+ * * `context_json` - Evaluation context as JSON string
+ *
+ * # Returns
+ *
+ * `true` if the request is allowed, `false` otherwise.
+ */
+export function policy_allows(policy_json: string, context_json: string): boolean;
+/**
+ * JavaScript-compatible detection result
+ */
+export class JsDetectionResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Whether the request was identified as coming from an agent
+   */
+  is_agent: boolean;
+  /**
+   * Confidence score (0.0 to 1.0 scale)
+   */
+  confidence: number;
+  /**
+   * Get the detected agent name
+   */
+  readonly agent: string | undefined;
+  /**
+   * Get the detection class for database storage
+   * Returns: 'human', 'ai_agent', 'bot', 'automation', or 'unknown'
+   */
+  readonly detection_class: string;
+  /**
+   * Get the verification method as a string
+   */
+  readonly verification_method: string;
+  /**
+   * Get the risk level as a string
+   */
+  readonly risk_level: string;
+  /**
+   * Get the timestamp as a string
+   */
+  readonly timestamp: string;
+}
+/**
+ * JavaScript-compatible result from did:key resolution
+ */
+export class JsDidKeyResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Whether the resolution was successful
+   */
+  success: boolean;
+  /**
+   * Get the public key as hex string
+   */
+  readonly public_key_hex: string | undefined;
+  /**
+   * Get the key type
+   */
+  readonly key_type: string | undefined;
+  /**
+   * Get the error message
+   */
+  readonly error: string | undefined;
+}
+/**
+ * JavaScript-compatible result from MCP-I verification
+ */
+export class JsMcpIVerificationResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Whether the verification was successful
+   */
+  verified: boolean;
+  /**
+   * Confidence score (0.0 to 1.0 scale) - 0.99 for verified MCP-I
+   */
+  confidence: number;
+  /**
+   * Get the issuer DID (principal)
+   */
+  readonly issuer_did: string | undefined;
+  /**
+   * Get the subject DID (agent)
+   */
+  readonly subject_did: string | undefined;
+  /**
+   * Get the error message
+   */
+  readonly error: string | undefined;
+}
+/**
+ * JavaScript-compatible policy evaluation result
+ */
+export class JsPolicyEvaluationResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Check if the action permits the request to proceed
+   * Returns true for 'allow' and 'log' (allow but log for monitoring)
+   */
+  is_allowed(): boolean;
+  /**
+   * Check if the action blocks the request
+   * Returns true for 'block', 'redirect', and 'challenge'
+   */
+  is_blocked(): boolean;
+  /**
+   * Convert to JSON string for serialization
+   */
+  to_json(): string;
+  /**
+   * Get the enforcement action
+   */
+  readonly action: string;
+  /**
+   * Get the reason for the action
+   */
+  readonly reason: string;
+  /**
+   * Get the matched rule ID
+   */
+  readonly rule_id: string | undefined;
+  /**
+   * Get the matched rule name
+   */
+  readonly rule_name: string | undefined;
+  /**
+   * Get the redirect URL
+   */
+  readonly redirect_url: string | undefined;
+  /**
+   * Get the custom message
+   */
+  readonly message: string | undefined;
+  /**
+   * Get the match type
+   */
+  readonly match_type: string;
+}
+/**
+ * JavaScript-compatible request metadata
+ */
+export class JsRequestMetadata {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Constructor for JsRequestMetadata
+   */
+  constructor(
+    user_agent: string | null | undefined,
+    ip_address: string | null | undefined,
+    headers: string,
+    timestamp: string,
+    url?: string | null,
+    method?: string | null,
+    client_fingerprint?: string | null,
+    tls_fingerprint?: string | null
+  );
+  /**
+   * Get the user agent
+   */
+  readonly user_agent: string | undefined;
+  /**
+   * Get the IP address
+   */
+  readonly ip_address: string | undefined;
+  /**
+   * Get the headers as JSON string
+   */
+  readonly headers: string;
+  /**
+   * Get the timestamp
+   */
+  readonly timestamp: string;
+  /**
+   * Get the URL
+   */
+  readonly url: string | undefined;
+  /**
+   * Get the method
+   */
+  readonly method: string | undefined;
+  /**
+   * Get the client fingerprint
+   */
+  readonly client_fingerprint: string | undefined;
+  /**
+   * Get the TLS fingerprint
+   */
+  readonly tls_fingerprint: string | undefined;
+}
+/**
+ * JavaScript-compatible result from scope check
+ */
+export class JsScopeCheckResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Whether the scope is permitted
+   */
+  permitted: boolean;
+  /**
+   * Get the matching scope
+   */
+  readonly matched_by: string | undefined;
+  /**
+   * Get the match type
+   */
+  readonly match_type: string;
+  /**
+   * Get the error message
+   */
+  readonly error: string | undefined;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_jsdetectionresult_free: (a: number, b: number) => void;
+  readonly __wbg_get_jsdetectionresult_is_agent: (a: number) => number;
+  readonly __wbg_set_jsdetectionresult_is_agent: (a: number, b: number) => void;
+  readonly __wbg_get_jsdetectionresult_confidence: (a: number) => number;
+  readonly __wbg_set_jsdetectionresult_confidence: (a: number, b: number) => void;
+  readonly jsdetectionresult_agent: (a: number, b: number) => void;
+  readonly jsdetectionresult_detection_class: (a: number, b: number) => void;
+  readonly jsdetectionresult_verification_method: (a: number, b: number) => void;
+  readonly jsdetectionresult_risk_level: (a: number, b: number) => void;
+  readonly jsdetectionresult_timestamp: (a: number, b: number) => void;
+  readonly __wbg_jsrequestmetadata_free: (a: number, b: number) => void;
+  readonly jsrequestmetadata_new: (
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: number,
+    f: number,
+    g: number,
+    h: number,
+    i: number,
+    j: number,
+    k: number,
+    l: number,
+    m: number,
+    n: number,
+    o: number,
+    p: number
+  ) => number;
+  readonly jsrequestmetadata_user_agent: (a: number, b: number) => void;
+  readonly jsrequestmetadata_ip_address: (a: number, b: number) => void;
+  readonly jsrequestmetadata_headers: (a: number, b: number) => void;
+  readonly jsrequestmetadata_timestamp: (a: number, b: number) => void;
+  readonly jsrequestmetadata_url: (a: number, b: number) => void;
+  readonly jsrequestmetadata_method: (a: number, b: number) => void;
+  readonly jsrequestmetadata_client_fingerprint: (a: number, b: number) => void;
+  readonly jsrequestmetadata_tls_fingerprint: (a: number, b: number) => void;
+  readonly init: () => void;
+  readonly detect_agent: (a: number, b: number) => void;
+  readonly get_version: (a: number) => void;
+  readonly get_build_info: (a: number) => void;
+  readonly __wbg_jsmcpiverificationresult_free: (a: number, b: number) => void;
+  readonly __wbg_get_jsmcpiverificationresult_verified: (a: number) => number;
+  readonly __wbg_set_jsmcpiverificationresult_verified: (a: number, b: number) => void;
+  readonly jsmcpiverificationresult_issuer_did: (a: number, b: number) => void;
+  readonly jsmcpiverificationresult_subject_did: (a: number, b: number) => void;
+  readonly jsmcpiverificationresult_error: (a: number, b: number) => void;
+  readonly verify_mcp_i_proof: (a: number, b: number, c: bigint) => number;
+  readonly __wbg_jsdidkeyresult_free: (a: number, b: number) => void;
+  readonly __wbg_get_jsdidkeyresult_success: (a: number) => number;
+  readonly __wbg_set_jsdidkeyresult_success: (a: number, b: number) => void;
+  readonly jsdidkeyresult_public_key_hex: (a: number, b: number) => void;
+  readonly jsdidkeyresult_key_type: (a: number, b: number) => void;
+  readonly jsdidkeyresult_error: (a: number, b: number) => void;
+  readonly resolve_did_key_wasm: (a: number, b: number) => number;
+  readonly __wbg_jsscopecheckresult_free: (a: number, b: number) => void;
+  readonly jsscopecheckresult_matched_by: (a: number, b: number) => void;
+  readonly jsscopecheckresult_match_type: (a: number, b: number) => void;
+  readonly jsscopecheckresult_error: (a: number, b: number) => void;
+  readonly check_delegation_scope: (a: number, b: number, c: number, d: number) => number;
+  readonly verify_delegation_scope: (
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: bigint,
+    f: bigint,
+    g: bigint
+  ) => number;
+  readonly __wbg_jspolicyevaluationresult_free: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_action: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_reason: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_rule_id: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_rule_name: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_redirect_url: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_message: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_match_type: (a: number, b: number) => void;
+  readonly jspolicyevaluationresult_is_allowed: (a: number) => number;
+  readonly jspolicyevaluationresult_is_blocked: (a: number) => number;
+  readonly jspolicyevaluationresult_to_json: (a: number, b: number) => void;
+  readonly evaluate_policy: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly policy_allows: (a: number, b: number, c: number, d: number) => number;
+  readonly version: (a: number) => void;
+  readonly __wbg_set_jsmcpiverificationresult_confidence: (a: number, b: number) => void;
+  readonly __wbg_get_jsmcpiverificationresult_confidence: (a: number) => number;
+  readonly __wbg_set_jsscopecheckresult_permitted: (a: number, b: number) => void;
+  readonly __wbg_get_jsscopecheckresult_permitted: (a: number) => number;
+  readonly __wbindgen_export: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_export2: (a: number, b: number) => number;
+  readonly __wbindgen_export3: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init(
+  module_or_path?:
+    | { module_or_path: InitInput | Promise<InitInput> }
+    | InitInput
+    | Promise<InitInput>
+): Promise<InitOutput>;