@agentbadge/pass-auth

Self-serve pass auth for AgentBadge marketplace services. Protect your API/MCP with on-chain service passes in ~3 lines — on-chain reads only, zero calls to agentbadge.xyz in the request path.

Install

npm i @agentbadge/pass-auth viem

Hono

import { honoPassAuth } from "@agentbadge/pass-auth";

app.use("/api/*", honoPassAuth({
  serviceId: "0x…",            // your service's bytes32 id
  domain: "api.acme.com",      // challenge domain (your origin)
}));
// c.get("agentWallet") → authenticated buyer wallet

Express

import { expressPassAuth } from "@agentbadge/pass-auth";

app.use("/api", expressPassAuth({ serviceId, domain: "api.acme.com" }));
// req.agentWallet → authenticated buyer wallet

MCP (streamable HTTP)

Token exchange — clients can't sign per-request, so they exchange a wallet signature for a 1h bearer token:

import { mcpPassAuth } from "@agentbadge/pass-auth";

const mcp = mcpPassAuth({ serviceId, domain: "mcp.acme.com", secret: process.env.AUTH_SECRET });

app.post("/auth/token", async (req, res) => {
  const r = await mcp.handleTokenRequest(req.body); // {wallet, signature, timestamp}
  res.status(r.status).json(r.body);                // → {token, expiresIn}
});

// on your MCP endpoint:
const auth = mcp.verifyBearer(req.headers.authorization);
if (!auth) return res.status(401).end();

Buyer side

import { signChallenge } from "@agentbadge/pass-auth";

const { signature, timestamp, wallet } = await signChallenge(viemAccount, "api.acme.com");
// → headers: X-Agent-Wallet / X-Agent-Signature / X-Agent-Timestamp
// → or POST {wallet, signature, timestamp} to /auth/token for MCP

Status codes

| Code | Meaning | |------|---------| | 401 | missing/malformed/expired/invalid signature (300s replay window) | | 402 | valid signature, no live service pass → buy at the marketplace |

Config

{ serviceId, domain, rpcUrl?, nftAddress?, secret?, tokenTtlSeconds? }

Defaults: Arc Testnet (chainId 5042002), MarketplacePassNFT 0xb42f7c30e4dc14877dac7948bfcb2db455df2962, blockdaemon RPC. hasAccess results are cached 300s (15s for negatives — fresh purchases unlock quickly). clearAccessCache() for tests.

Signature verification covers EOA (local ecrecover), ERC-1271 contract wallets, and ERC-6492 counterfactual signatures via viem.