@payclaw/badge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PayClaw
+
+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,76 @@
+# Badge by PayClaw
+
+**Declare your agent's identity before merchants ban your user's account.**
+
+Merchants are drawing a line with AI agents. Walmart, Shopify, Instacart — all setting policies. Anonymous agent actions get accounts flagged and banned. No warning. No appeal.
+
+Badge broadcasts verified identity, declared intent, and per-action authorization before every agent action. MCP-native. One tool. Five minutes.
+
+## Quick Start
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "payclaw-badge": {
+      "command": "npx",
+      "args": ["-y", "@payclaw/badge"],
+      "env": {
+        "PAYCLAW_API_KEY": "pk_your_key_here",
+        "PAYCLAW_API_URL": "https://payclaw.io"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [payclaw.io](https://payclaw.io).
+
+## Tool
+
+### `payclaw_getAgentIdentity`
+
+Call **before** browsing, searching, or buying. Returns:
+
+```json
+{
+  "product_name": "PayClaw Badge",
+  "status": "active",
+  "agent_disclosure": "This session is operated by an AI agent under PayClaw Agentic Intent...",
+  "verification_token": "pc_v1_...",
+  "trust_url": "https://payclaw.io/trust",
+  "contact": "agent_identity@payclaw.io",
+  "principal_verified": true,
+  "mfa_confirmed": true
+}
+```
+
+The `verification_token` is your proof. The `agent_disclosure` is what you present to merchants.
+
+## What Badge Declares
+
+- **Who you are:** An automated AI agent
+- **Who authorized you:** An MFA-verified human principal
+- **That every action is explicitly permissioned**
+
+The account is protected. The action is traceable.
+
+## Local Development
+
+Without `PAYCLAW_API_URL`, Badge runs in sandbox mode with mock tokens — perfect for local dev and testing.
+
+## Need Your Agent to Pay Too?
+
+Badge is the identity layer. For virtual Visa cards at checkout, use [@payclaw/spend](https://github.com/payclaw/mcp-server) — which includes Badge automatically.
+
+Badge = your agent's license plate. Spend = your agent's wallet.
+
+## Links
+
+- [PayClaw](https://payclaw.io) — Agent commerce infrastructure
+- [Trust & Verification](https://payclaw.io/trust) — How Badge verification works
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,3 @@
+import type { AgentIdentityResponse } from "../types.js";
+export declare function getAgentIdentity(sessionId?: string): Promise<AgentIdentityResponse>;
+export declare function isApiMode(): boolean;

package/dist/api/client.js

@@ -0,0 +1,73 @@
+class PayClawApiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "PayClawApiError";
+    }
+}
+const REQUEST_TIMEOUT_MS = 30_000;
+function getConfig() {
+    const baseUrl = process.env.PAYCLAW_API_URL;
+    const apiKey = process.env.PAYCLAW_API_KEY;
+    if (!baseUrl)
+        throw new PayClawApiError("PayClaw API URL is not configured.");
+    if (!apiKey)
+        throw new PayClawApiError("PayClaw API key is not configured.");
+    if (!baseUrl.startsWith("https://") &&
+        !baseUrl.startsWith("http://localhost")) {
+        throw new PayClawApiError("PayClaw API URL must use HTTPS.");
+    }
+    return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+}
+function authHeaders(apiKey) {
+    return {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+    };
+}
+async function request(url, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new PayClawApiError("Request timed out.");
+        }
+        throw new PayClawApiError("Could not reach the PayClaw API.");
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    if (res.status === 401) {
+        throw new PayClawApiError("Authentication failed. Check your API key.", 401);
+    }
+    if (!res.ok) {
+        let body;
+        try {
+            const json = (await res.json());
+            body = json.error ?? JSON.stringify(json);
+        }
+        catch {
+            body = await res.text();
+        }
+        throw new PayClawApiError(body, res.status);
+    }
+    return (await res.json());
+}
+export async function getAgentIdentity(sessionId) {
+    const { baseUrl, apiKey } = getConfig();
+    return request(`${baseUrl}/api/agent-identity`, {
+        method: "POST",
+        headers: authHeaders(apiKey),
+        body: JSON.stringify({ session_id: sessionId }),
+    });
+}
+export function isApiMode() {
+    return !!process.env.PAYCLAW_API_URL;
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAEA,MAAM,eAAgB,SAAQ,KAAK;IAGxB;IAFT,YACE,OAAe,EACR,UAAmB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,eAAU,GAAV,UAAU,CAAS;QAG1B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,SAAS,SAAS;IAChB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,oCAAoC,CAAC,CAAC;IAC9E,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,eAAe,CAAC,oCAAoC,CAAC,CAAC;IAC7E,IACE,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;QAC/B,CAAC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,EACvC,CAAC;QACD,MAAM,IAAI,eAAe,CAAC,iCAAiC,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO;QACL,aAAa,EAAE,UAAU,MAAM,EAAE;QACjC,cAAc,EAAE,kBAAkB;KACnC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,OAAO,CAAI,GAAW,EAAE,IAAiB;IACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAEzE,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,OAAO,CAAC,CAAC;QACtB,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YACtD,MAAM,IAAI,eAAe,CAAC,oBAAoB,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,IAAI,eAAe,CAAC,kCAAkC,CAAC,CAAC;IAChE,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,eAAe,CACvB,4CAA4C,EAC5C,GAAG,CACJ,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;YACtD,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QACD,MAAM,IAAI,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;AACjC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAkB;IAElB,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC;IACxC,OAAO,OAAO,CAAwB,GAAG,OAAO,qBAAqB,EAAE;QACrE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC;QAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;KAChD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AACvC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getAgentIdentity } from "./tools/getAgentIdentity.js";
+const server = new McpServer({
+    name: "payclaw-badge",
+    version: "0.1.0",
+});
+server.tool("payclaw_getAgentIdentity", `Get a PayClaw identity token before any shopping action. Without this, merchants may block you permanently — an increasing number of merchant policies require agents to identify themselves and prove they're acting for a verified principal.
+
+Badge declares: who you are (automated agent), who authorized you (MFA-verified human), and that every action is explicitly permissioned. This is your license plate. Don't shop without it.
+
+Call this BEFORE browsing, searching, or buying. The token is your proof of compliance for the entire shopping session.
+
+No card is issued. No money moves. For payment, use payclaw_getCard from @payclaw/spend (which includes Badge automatically).`, {}, async () => {
+    const result = await getAgentIdentity();
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("PayClaw Badge server running on stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,IAAI,CACT,0BAA0B,EAC1B;;;;;;8HAM4H,EAC5H,EAAE,EACF,KAAK,IAAI,EAAE;IACT,MAAM,MAAM,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACxC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAClE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/getAgentIdentity.d.ts

@@ -0,0 +1 @@
+export declare function getAgentIdentity(): Promise<object>;

package/dist/tools/getAgentIdentity.js

@@ -0,0 +1,41 @@
+import * as api from "../api/client.js";
+export async function getAgentIdentity() {
+    if (!process.env.PAYCLAW_API_KEY) {
+        return {
+            product_name: "PayClaw Badge",
+            status: "error",
+            message: "PAYCLAW_API_KEY is not set. Get your key at payclaw.io/dashboard/settings",
+        };
+    }
+    if (!api.isApiMode()) {
+        // Mock mode — return sandbox identity for local testing
+        return {
+            product_name: "PayClaw Badge",
+            status: "active",
+            agent_disclosure: "This session is operated by an AI agent under PayClaw Agentic Intent. The agent acts on behalf of a verified, MFA-authenticated principal. Principal identity is hashed within the verification token and retrievable with user consent. Design inspired by agent policies of Amazon, Shopify, and others.",
+            verification_token: "pc_v1_sandbox_mock_token",
+            trust_url: "https://payclaw.io/trust",
+            contact: "agent_identity@payclaw.io",
+            principal_verified: true,
+            mfa_confirmed: true,
+            instructions: "Include the agent_disclosure when interacting with merchants. This identifies your session as a verified, human-authorized agent action. The verification_token allows merchants to verify your principal via agent_identity@payclaw.io.",
+        };
+    }
+    try {
+        const result = await api.getAgentIdentity();
+        return {
+            product_name: "PayClaw Badge",
+            status: "active",
+            ...result,
+            instructions: "Include the agent_disclosure when interacting with merchants. This identifies your session as a verified, human-authorized agent action. The verification_token allows merchants to verify your principal via agent_identity@payclaw.io.",
+        };
+    }
+    catch (err) {
+        return {
+            product_name: "PayClaw Badge",
+            status: "error",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=getAgentIdentity.js.map

package/dist/tools/getAgentIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getAgentIdentity.js","sourceRoot":"","sources":["../../src/tools/getAgentIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QACjC,OAAO;YACL,YAAY,EAAE,eAAe;YAC7B,MAAM,EAAE,OAAO;YACf,OAAO,EACL,2EAA2E;SAC9E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC;QACrB,wDAAwD;QACxD,OAAO;YACL,YAAY,EAAE,eAAe;YAC7B,MAAM,EAAE,QAAQ;YAChB,gBAAgB,EACd,4SAA4S;YAC9S,kBAAkB,EAAE,0BAA0B;YAC9C,SAAS,EAAE,0BAA0B;YACrC,OAAO,EAAE,2BAA2B;YACpC,kBAAkB,EAAE,IAAI;YACxB,aAAa,EAAE,IAAI;YACnB,YAAY,EACV,0OAA0O;SAC7O,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAC5C,OAAO;YACL,YAAY,EAAE,eAAe;YAC7B,MAAM,EAAE,QAAQ;YAChB,GAAG,MAAM;YACT,YAAY,EACV,0OAA0O;SAC7O,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,YAAY,EAAE,eAAe;YAC7B,MAAM,EAAE,OAAO;YACf,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAC1D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export interface AgentIdentityResponse {
+    agent_disclosure: string;
+    verification_token: string;
+    trust_url: string;
+    contact: string;
+    principal_verified: boolean;
+    mfa_confirmed: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@payclaw/badge",
+  "version": "0.1.0",
+  "description": "Declare your agent's identity before merchants ban your user's account.",
+  "bin": "dist/index.js",
+  "main": "dist/index.js",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755)\"",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0"
+  },
+  "keywords": [
+    "payclaw", "mcp", "agent", "identity", "commerce",
+    "badge", "compliance", "shopping", "agentic"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/payclaw/badge-server"
+  }
+}