clawpass-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawPass Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# clawpass-sdk 🛡️
+
+**Logic-Driven Authentication Layer for Autonomous Agents**
+
+ClawPass is a specialized middleware designed for the **M2M (Machine-to-Machine) economy**.
+It separates autonomous AI agents from human noise and malicious scripts by deploying **non-deterministic logic gates** that must be solved at machine-speed.
+
+[🌐 Website](https://www.clawpass.tech) | [🐦 Twitter|X](https://x.com/claw_pass) | [📖 Documentation](https://clawpass.tech/docs)
+
+---
+
+# 🚀 Installation
+
+Install the SDK via npm or yarn.
+
+```bash
+npm install clawpass-sdk
+```
+
+or
+
+```bash
+yarn add clawpass-sdk
+```
+
+or
+
+```bash
+pnpm add clawpass-sdk
+```
+
+or
+
+```bash
+bun add clawpass-sdk
+```
+
+---
+
+# 🛠️ Quick Start
+
+## 1. Initialize ClawPass
+
+Create an instance using your secret key.
+
+> Secret key must be **minimum 32 characters**.
+
+```ts
+import { ClawPass } from 'clawpass-sdk'
+
+const claw = new ClawPass({
+  secretKey: 'your-ultra-secure-32-char-secret-key',
+  maxLatencyMs: 1000 // 1 second threshold for autonomous verification  
+})
+```
+
+---
+
+# 2. Express Middleware Integration
+
+Protect your API routes easily.
+
+If a request does not contain a valid **ClawPass Stamp**, it will automatically be challenged with a logic gate.
+
+```ts
+import express from 'express'
+import { requireAgent } from 'clawpass-sdk'
+
+const app = express()
+
+app.post('/api/execute-task', requireAgent(claw), (req, res) => {
+  res.json({
+    message: "Access granted to verified agent."
+  })
+})
+```
+
+---
+
+# 3. Manual Agent Evaluation
+
+When an agent submits a solution to a challenge, verify the result and issue a **cryptographic passport (stamp)**.
+
+```ts
+app.post('/api/verify', (req, res) => {
+  const { challenge, answer, requestTimestamp } = req.body
+
+  const result = claw.evaluateAgent(
+    challenge,
+    answer,
+    requestTimestamp
+  )
+
+  if (result.success) {
+    res.json({
+      success: true,
+      stamp: result.stamp
+    })
+  } else {
+    res.status(403).json({
+      success: false,
+      reason: result.reason
+    })
+  }
+})
+```
+
+---
+
+# 🧩 Core Concepts
+
+| Feature            | Description                                                                  |
+|--------------------|------------------------------------------------------------------------------|
+| Logic Gates        | Non-deterministic mathematical challenges that require reasoning depth       |
+| Machine-Speed      | Strict latency enforcement (default `<1000ms`) to prevent human interference |
+| Stateless Stamping | HMAC-SHA256 signed passports without server-side session storage             |
+
+---
+
+# 🔒 Security Requirements
+
+### Secret Key
+
+Must be at least **32 characters long**.
+
+### Timestamp Verification
+
+Clients must include the following header in their requests:
+
+```
+x-clawpass-timestamp
+```
+
+This allows the server to verify that the challenge was solved within the allowed latency window.
+
+---
+
+# 🌐 Target Use Cases
+
+* Autonomous AI agents
+* On-chain bots
+* Trading agents
+* Automation networks
+* M2M API ecosystems
+
+---
+
+# 🔗 Resources & Contact
+
+* **Website:** [clawpass.tech](https://www.clawpass.tech)
+* **Twitter:** [@claw_pass](https://x.com/claw_pass)
+* **Support:** support@clawpass.tech
+
+---
+
+# 📄 License
+
+MIT License
+© ClawPass

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const CLAWPASS_CONSTANTS: {
+    DEFAULT_PASSPORT_VALIDITY_MS: number;
+    MIN_SECRET_KEY_LENGTH: number;
+    DEFAULT_CHALLENGE_TIMEOUT_MS: number;
+    HEADERS: {
+        CHALLENGE: string;
+        RESPONSE: string;
+        STAMP: string;
+        QUESTION: string;
+        TIMESTAMP: string;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAWPASS_CONSTANTS = void 0;
+exports.CLAWPASS_CONSTANTS = {
+    // Security & Crypto
+    DEFAULT_PASSPORT_VALIDITY_MS: 3600000, // 1 Hour
+    MIN_SECRET_KEY_LENGTH: 32,
+    // Timing & Machine-Speed Limits
+    DEFAULT_CHALLENGE_TIMEOUT_MS: 1000,
+    // Standardized Header Names
+    HEADERS: {
+        CHALLENGE: 'x-clawpass-challenge',
+        RESPONSE: 'x-clawpass-response',
+        STAMP: 'x-clawpass-stamp',
+        QUESTION: 'x-clawpass-question',
+        TIMESTAMP: 'x-clawpass-timestamp'
+    }
+};

package/dist/core/ClawPass.d.ts

@@ -0,0 +1,30 @@
+import { Challenge } from '../engine/ChallengeFactory';
+import { ClawPassOptions } from './Config';
+export declare class ClawPass {
+    private issuer;
+    private challengeFactory;
+    private readonly config;
+    constructor(options: ClawPassOptions);
+    /**
+     * Validates an existing passport stamp.
+     */
+    isAuthorized(stamp?: string): boolean;
+    /**
+     * Generates a new logic-gate challenge.
+     */
+    deployGate(): Challenge;
+    /**
+     * Evaluates the agent's solution and issues a cryptographic stamp.
+     */
+    evaluateAgent(challenge: Challenge, agentAnswer: number | string, requestTimeMs: number): {
+        success: boolean;
+        reason: string | undefined;
+        latency: number;
+        stamp?: undefined;
+    } | {
+        success: boolean;
+        stamp: string;
+        latency: number;
+        reason?: undefined;
+    };
+}

package/dist/core/ClawPass.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawPass = void 0;
+const PassportIssuer_1 = require("../crypto/PassportIssuer");
+const ChallengeFactory_1 = require("../engine/ChallengeFactory");
+const Verifier_1 = require("../engine/Verifier");
+const Config_1 = require("./Config"); // Importing the Config engine
+class ClawPass {
+    constructor(options) {
+        this.config = new Config_1.Config(options);
+        this.issuer = new PassportIssuer_1.PassportIssuer(this.config.secretKey);
+        this.challengeFactory = new ChallengeFactory_1.ChallengeFactory();
+    }
+    /**
+     * Validates an existing passport stamp.
+     */
+    isAuthorized(stamp) {
+        if (!stamp)
+            return false;
+        const payload = this.issuer.verifyStamp(stamp);
+        return payload !== null && payload.isAgent;
+    }
+    /**
+     * Generates a new logic-gate challenge.
+     */
+    deployGate() {
+        return ChallengeFactory_1.ChallengeFactory.generateSequence();
+    }
+    /**
+     * Evaluates the agent's solution and issues a cryptographic stamp.
+     */
+    evaluateAgent(challenge, agentAnswer, requestTimeMs) {
+        const verification = Verifier_1.Verifier.verifyResponse(challenge, agentAnswer, requestTimeMs, this.config.maxLatencyMs);
+        if (!verification.isValid) {
+            return {
+                success: false,
+                reason: verification.reason,
+                latency: verification.latencyMs
+            };
+        }
+        const stamp = this.issuer.issueStamp(challenge.id, verification.latencyMs);
+        return {
+            success: true,
+            stamp,
+            latency: verification.latencyMs
+        };
+    }
+}
+exports.ClawPass = ClawPass;

package/dist/core/Config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Configuration options for the ClawPass SDK instance.
+ */
+export interface ClawPassOptions {
+    secretKey: string;
+    maxLatencyMs?: number;
+    difficulty?: 'easy' | 'medium' | 'hard';
+}
+/**
+ * Centralized Configuration Manager for ClawPass.
+ * Handles validation and default values for the entire SDK.
+ */
+export declare class Config {
+    readonly secretKey: string;
+    readonly maxLatencyMs: number;
+    readonly difficulty: string;
+    constructor(options: ClawPassOptions);
+    /**
+     * Ensures all critical configuration parameters meet security standards.
+     */
+    private validate;
+}

package/dist/core/Config.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+const constants_1 = require("../constants");
+/**
+ * Centralized Configuration Manager for ClawPass.
+ * Handles validation and default values for the entire SDK.
+ */
+class Config {
+    constructor(options) {
+        this.secretKey = options.secretKey;
+        this.maxLatencyMs = options.maxLatencyMs || constants_1.CLAWPASS_CONSTANTS.DEFAULT_CHALLENGE_TIMEOUT_MS;
+        this.difficulty = options.difficulty || 'medium';
+        this.validate();
+    }
+    /**
+     * Ensures all critical configuration parameters meet security standards.
+     */
+    validate() {
+        if (!this.secretKey || this.secretKey.length < constants_1.CLAWPASS_CONSTANTS.MIN_SECRET_KEY_LENGTH) {
+            throw new Error(`ClawPass Security: secretKey must be at least ${constants_1.CLAWPASS_CONSTANTS.MIN_SECRET_KEY_LENGTH} characters.`);
+        }
+    }
+}
+exports.Config = Config;

package/dist/crypto/PassportIssuer.d.ts

@@ -0,0 +1,27 @@
+export interface PassportPayload {
+    gateId: string;
+    isAgent: boolean;
+    latencyMs: number;
+    issuedAt: number;
+    expiresAt: number;
+}
+/**
+ * Metadata stored within the ClawPass cryptographic stamp.
+ */
+export declare class PassportIssuer {
+    private readonly secretKey;
+    private readonly validityPeriodMs;
+    constructor(secretKey: string, validityMs?: number);
+    /**
+     * Issues a signed cryptographic stamp (Passport) for a verified agent.
+     */
+    issueStamp(gateId: string, latencyMs: number): string;
+    /**
+     * Verifies the authenticity and expiration of a ClawPass stamp.
+     */
+    verifyStamp(stamp: string): PassportPayload | null;
+    /**
+     * Internal HMAC-SHA256 signing mechanism
+     */
+    private sign;
+}

package/dist/crypto/PassportIssuer.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PassportIssuer = void 0;
+const crypto_1 = require("crypto");
+const constants_1 = require("../constants");
+/**
+ * Metadata stored within the ClawPass cryptographic stamp.
+ */
+class PassportIssuer {
+    constructor(secretKey, validityMs) {
+        if (!secretKey || secretKey.length < constants_1.CLAWPASS_CONSTANTS.MIN_SECRET_KEY_LENGTH) {
+            throw new Error(`ClawPass Security: Secret key must be at least ${constants_1.CLAWPASS_CONSTANTS.MIN_SECRET_KEY_LENGTH} characters.`);
+        }
+        this.secretKey = secretKey;
+        this.validityPeriodMs = validityMs || constants_1.CLAWPASS_CONSTANTS.DEFAULT_PASSPORT_VALIDITY_MS;
+    }
+    /**
+     * Issues a signed cryptographic stamp (Passport) for a verified agent.
+     */
+    issueStamp(gateId, latencyMs) {
+        const payload = {
+            gateId,
+            isAgent: true,
+            latencyMs,
+            issuedAt: Date.now(),
+            expiresAt: Date.now() + this.validityPeriodMs
+        };
+        const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+        const signature = this.sign(encodedPayload);
+        return `${encodedPayload}.${signature}`;
+    }
+    /**
+     * Verifies the authenticity and expiration of a ClawPass stamp.
+     */
+    verifyStamp(stamp) {
+        try {
+            if (!stamp || typeof stamp !== 'string')
+                return null;
+            const [encodedPayload, signature] = stamp.split('.');
+            if (!encodedPayload || !signature)
+                return null;
+            const expectedSignature = this.sign(encodedPayload);
+            if (signature !== expectedSignature) {
+                console.error("ClawPass Security: Stamp signature mismatch.");
+                return null;
+            }
+            const payload = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf-8'));
+            if (Date.now() > payload.expiresAt)
+                return null;
+            return payload;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Internal HMAC-SHA256 signing mechanism
+     */
+    sign(data) {
+        return (0, crypto_1.createHmac)('sha256', this.secretKey)
+            .update(data)
+            .digest('base64url');
+    }
+}
+exports.PassportIssuer = PassportIssuer;

package/dist/engine/ChallengeFactory.d.ts

@@ -0,0 +1,14 @@
+export interface Challenge {
+    id: string;
+    type: 'sequence_prediction' | 'math_equation' | 'logic_gate';
+    payload: string;
+    expectedAnswer: number;
+    createdAt: number;
+}
+export declare class ChallengeFactory {
+    /**
+     * Generates a sequence prediction challenge.
+     * Example: [5, 10, 20, 40, ?] -> Expected: 80
+     */
+    static generateSequence(): Challenge;
+}

package/dist/engine/ChallengeFactory.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChallengeFactory = void 0;
+class ChallengeFactory {
+    /**
+     * Generates a sequence prediction challenge.
+     * Example: [5, 10, 20, 40, ?] -> Expected: 80
+     */
+    static generateSequence() {
+        const multiplier = Math.floor(Math.random() * 4) + 2; // 2 to 5
+        const start = Math.floor(Math.random() * 10) + 1;
+        const sequence = [
+            start,
+            start * multiplier,
+            start * Math.pow(multiplier, 2),
+            start * Math.pow(multiplier, 3)
+        ];
+        const expectedAnswer = start * Math.pow(multiplier, 4);
+        return {
+            id: `gate_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
+            type: 'sequence_prediction',
+            payload: `[${sequence.join(', ')}, ?]`,
+            expectedAnswer,
+            createdAt: Date.now()
+        };
+    }
+}
+exports.ChallengeFactory = ChallengeFactory;

package/dist/engine/Verifier.d.ts

@@ -0,0 +1,13 @@
+import { Challenge } from './ChallengeFactory';
+export interface VerificationResult {
+    isValid: boolean;
+    latencyMs: number;
+    reason?: string;
+}
+export declare class Verifier {
+    /**
+     * Verifies if the agent's response matches the expected answer
+     * and fulfills the machine-speed latency requirements.
+     */
+    static verifyResponse(challenge: Challenge, receivedAnswer: string | number, requestTimestamp: number, timeoutLimit?: number): VerificationResult;
+}

package/dist/engine/Verifier.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Verifier = void 0;
+const constants_1 = require("../constants");
+class Verifier {
+    /**
+     * Verifies if the agent's response matches the expected answer
+     * and fulfills the machine-speed latency requirements.
+     */
+    static verifyResponse(challenge, receivedAnswer, requestTimestamp, timeoutLimit = constants_1.CLAWPASS_CONSTANTS.DEFAULT_CHALLENGE_TIMEOUT_MS) {
+        const currentTime = Date.now();
+        const latencyMs = currentTime - requestTimestamp;
+        // 1. Latency Check: Ensure the response arrived within the autonomous agent threshold
+        if (latencyMs > timeoutLimit) {
+            return {
+                isValid: false,
+                latencyMs,
+                reason: 'LATENCY_EXCEEDED'
+            };
+        }
+        // 2. Integrity Check: Ensure challenge isn't too old (Replay protection)
+        const challengeAge = currentTime - challenge.createdAt;
+        if (challengeAge > timeoutLimit * 5) { // Challenges expire after 5x timeout
+            return {
+                isValid: false,
+                latencyMs,
+                reason: 'CHALLENGE_EXPIRED'
+            };
+        }
+        // 3. Mathematical Verification: Compare expected vs received
+        // Converting to string for safe comparison of numbers/strings
+        const isCorrect = String(receivedAnswer) === String(challenge.expectedAnswer);
+        if (!isCorrect) {
+            return {
+                isValid: false,
+                latencyMs,
+                reason: 'INCORRECT_ANSWER'
+            };
+        }
+        return {
+            isValid: true,
+            latencyMs
+        };
+    }
+}
+exports.Verifier = Verifier;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './constants';
+export * from './core/ClawPass';
+export * from './crypto/PassportIssuer';
+export * from './engine/ChallengeFactory';
+export * from './engine/Verifier';
+export * from './integrations/express';
+export declare const SDK_VERSION = "1.0.0";

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+// 1. Export Constants
+__exportStar(require("./constants"), exports);
+// 2. Export Core Logic
+__exportStar(require("./core/ClawPass"), exports);
+// 3. Export Cryptographic Tools
+__exportStar(require("./crypto/PassportIssuer"), exports);
+// 4. Export Engine Components
+__exportStar(require("./engine/ChallengeFactory"), exports);
+__exportStar(require("./engine/Verifier"), exports);
+// 5. Export Integrations (Express, etc.)
+__exportStar(require("./integrations/express"), exports);
+// SDK Metadata
+exports.SDK_VERSION = '1.0.0';

package/dist/integrations/express.d.ts

@@ -0,0 +1,8 @@
+import { Request, Response, NextFunction } from 'express';
+import { ClawPass } from '../core/ClawPass';
+/**
+ * Express middleware to protect routes, ensuring only verified autonomous agents can access them.
+ * * @param clawpass - The initialized ClawPass SDK instance.
+ * @returns Express middleware function.
+ */
+export declare const requireAgent: (clawpass: ClawPass) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/integrations/express.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireAgent = void 0;
+const constants_1 = require("../constants");
+/**
+ * Express middleware to protect routes, ensuring only verified autonomous agents can access them.
+ * * @param clawpass - The initialized ClawPass SDK instance.
+ * @returns Express middleware function.
+ */
+const requireAgent = (clawpass) => {
+    return (req, res, next) => {
+        // 1. Extract the passport stamp from the headers using centralized constants
+        const stamp = req.headers[constants_1.CLAWPASS_CONSTANTS.HEADERS.STAMP];
+        // 2. Fast-Path: Validate the stamp statelessly
+        if (stamp && clawpass.isAuthorized(stamp)) {
+            // Stamp is valid. The entity is a verified agent.
+            return next();
+        }
+        // 3. Slow-Path: Entity is unverified. Intercept and deploy a logic-gate.
+        const challenge = clawpass.deployGate();
+        // 4. Return the challenge to the requester (Agent) with standardized headers
+        res.setHeader(constants_1.CLAWPASS_CONSTANTS.HEADERS.CHALLENGE, challenge.id);
+        res.status(401).json({
+            error: 'Unauthorized: Autonomous Identity Required.',
+            instruction: 'Solve the logic-gate and submit the answer to acquire a ClawPass stamp.',
+            gate: {
+                id: challenge.id,
+                type: challenge.type,
+                payload: challenge.payload,
+                createdAt: challenge.createdAt
+            }
+        });
+    };
+};
+exports.requireAgent = requireAgent;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "clawpass-sdk",
+  "version": "1.0.1",
+  "description": "Logic-Driven Authentication Layer for Autonomous Agents.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "base",
+    "ai",
+    "autonomous-agents",
+    "authentication",
+    "web3",
+    "middleware",
+    "clawpass"
+  ],
+  "author": "ClawPass",
+  "homepage": "https://www.clawpass.tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawpass/clawpass-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/clawpass/clawpass-sdk/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.3.3",
+    "typescript": "^5.9.3"
+  }
+}