@agentvisa/verify 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# @agentvisa/verify
+
+Verify human-authorized AI agents in one call. Drop into any Node.js backend — Express, Fastify, Next.js, or plain `fetch`. Supports [Web Bot Auth (RFC 9421)](https://blog.cloudflare.com/web-bot-auth/) via the `AgentVisa-Assertion` header.
+
+```bash
+npm install @agentvisa/verify
+```
+
+---
+
+## The two-layer model
+
+Cloudflare's [Web Bot Auth](https://blog.cloudflare.com/web-bot-auth/) tells you **which company's agent** is making a request — operator identity, cryptographically signed. It stops there by design. AgentVisa adds the missing half:
+
+```
+Layer 1 — Web Bot Auth (Cloudflare)
+  "This request is from Acme Corp's agent — verified."
+
+Layer 2 — AgentVisa (this library)
+  "A real human (Face ID, just now) authorized that agent to act."
+```
+
+When both are present, the `AgentVisa-Assertion` token is covered by the RFC 9421 signature — operator identity and human authorization cryptographically bound in one request.
+
+---
+
+## Quick start
+
+Get your `widgetId` and `apiKey` from your [AgentVisa dashboard](https://agentvisa.ai/dashboard/vendor).
+
+### Express middleware
+
+```typescript
+import express from 'express';
+import { agentVisa } from '@agentvisa/verify';
+
+const app = express();
+
+// Reject any request without a valid AgentVisa token
+app.use('/api', agentVisa({
+  widgetId: process.env.AGENTVISA_WIDGET_ID!,
+  apiKey:   process.env.AGENTVISA_API_KEY!,
+}));
+
+app.post('/api/checkout', (req, res) => {
+  // req.agentVisa is populated — token is valid
+  res.json({ ok: true });
+});
+```
+
+### Flag mode (decide in your handler)
+
+```typescript
+app.use(agentVisa({
+  widgetId: process.env.AGENTVISA_WIDGET_ID!,
+  apiKey:   process.env.AGENTVISA_API_KEY!,
+  onFail: 'flag',   // don't auto-reject — let the handler decide
+}));
+
+app.post('/api/order', (req, res) => {
+  if (!req.agentVisa?.valid) {
+    // Downgrade: show a CAPTCHA, require extra confirmation, etc.
+    return res.status(401).json({ error: 'human_required' });
+  }
+  // Full trust path
+  res.json({ ok: true });
+});
+```
+
+### Standalone (any framework)
+
+```typescript
+import { extractToken, verify } from '@agentvisa/verify';
+
+// Works with any framework — Next.js, Fastify, plain Node http, etc.
+async function handler(req, res) {
+  const { token } = extractToken(req.headers);
+  if (!token) return res.status(401).json({ error: 'agentvisa_required' });
+
+  const result = await verify(token, {
+    widgetId: process.env.AGENTVISA_WIDGET_ID!,
+    apiKey:   process.env.AGENTVISA_API_KEY!,
+  });
+
+  if (!result.valid) return res.status(401).json({ error: result.reason });
+  // Proceed
+}
+```
+
+### Web Bot Auth (RFC 9421)
+
+When an agent sends `AgentVisa-Assertion` instead of `X-AgentVisa-Token`, the library detects that the token was bound in a Web Bot Auth signature and reports it:
+
+```typescript
+app.post('/api/action', (req, res) => {
+  const av = req.agentVisa!;
+
+  console.log(av.valid);           // true  — human verified
+  console.log(av.webBotAuthBound); // true  — token covered by RFC 9421 signature
+                                   // false — arrived via X-AgentVisa-Token (standard)
+
+  // Both true = complete trust: which agent + which human, cryptographically bound
+});
+```
+
+> **Note:** `webBotAuthBound: true` confirms the structural binding is present. The RFC 9421 signature cryptography is verified by your WAF/CDN (e.g. Cloudflare Web Bot Auth) before the request reaches your app.
+
+---
+
+## API reference
+
+### `agentVisa(options)` — Express middleware
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `widgetId` | `string` | ✓ | Your `wgt_xxx` widget ID |
+| `apiKey` | `string` | ✓ | Your `wk_xxx` API key |
+| `onFail` | `'reject' \| 'flag'` | — | `'reject'` (default) sends 401; `'flag'` sets `req.agentVisa` and continues |
+| `rejectBody` | `object` | — | Custom body for 401 responses |
+| `apiUrl` | `string` | — | Override API base URL (testing) |
+
+Attaches `req.agentVisa: VerifyResult & { token: string \| null }` to the request.
+
+---
+
+### `verify(token, options, headers?)` — standalone
+
+```typescript
+const result = await verify(token, { widgetId, apiKey }, req.headers);
+```
+
+Returns a `VerifyResult`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `valid` | `boolean` | Token is valid and human is verified |
+| `humanVerified` | `boolean` | Alias for `valid` |
+| `reason` | `string` | `'ok'` or error code |
+| `verifiedAt` | `string` | ISO timestamp of human verification |
+| `expiresAt` | `string` | ISO timestamp of token expiry |
+| `domainVerified` | `boolean` | Requesting domain is verified by the Widget Holder |
+| `webBotAuthBound` | `boolean` | Token was covered by RFC 9421 Signature-Input |
+| `raw` | `object` | Raw AgentVisa API response |
+
+---
+
+### `extractToken(headers)` — utility
+
+```typescript
+const { token, source } = extractToken(req.headers);
+// source: 'assertion' | 'header' | null
+// 'assertion' = AgentVisa-Assertion header (Web Bot Auth mode)
+// 'header'    = X-AgentVisa-Token header (standard mode)
+```
+
+---
+
+## How agents send the token
+
+Agents use the [AgentVisa MCP server](https://github.com/AgentVisa-ai/agentvisa/tree/main/mcp) (`@agentvisa/mcp`) to get a `tmp_xxx` token, then send it in one of two ways:
+
+**Standard mode:**
+```
+X-AgentVisa-Token: tmp_xxxxxxxxxxxxxxxxxxxx
+```
+
+**Web Bot Auth mode** (RFC 9421 — token bound in the signature):
+```
+AgentVisa-Assertion: tmp_xxxxxxxxxxxxxxxxxxxx
+Signature-Input: sig1=("@method" "@path" "host" "agentvisa-assertion");keyid="acme-bot-key";created=1234567890
+Signature: sig1=:base64sig:
+```
+
+---
+
+## License
+
+MIT · [agentvisa.ai](https://agentvisa.ai)

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @agentvisa/verify
+ *
+ * Verify human-authorized AI agents in one call.
+ * Works standalone or as Express middleware.
+ * Supports Web Bot Auth (RFC 9421) via AgentVisa-Assertion header.
+ *
+ * @example
+ * // Standalone
+ * import { extractToken, verify } from '@agentvisa/verify';
+ * const { token } = extractToken(req.headers);
+ * const result = await verify(token, { widgetId, apiKey });
+ *
+ * @example
+ * // Express middleware
+ * import { agentVisa } from '@agentvisa/verify';
+ * app.use('/api', agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ */
+export { extractToken, verify } from './verify.js';
+export { agentVisa } from './middleware.js';
+export type { VerifyOptions, VerifyResult, MiddlewareOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @agentvisa/verify
+ *
+ * Verify human-authorized AI agents in one call.
+ * Works standalone or as Express middleware.
+ * Supports Web Bot Auth (RFC 9421) via AgentVisa-Assertion header.
+ *
+ * @example
+ * // Standalone
+ * import { extractToken, verify } from '@agentvisa/verify';
+ * const { token } = extractToken(req.headers);
+ * const result = await verify(token, { widgetId, apiKey });
+ *
+ * @example
+ * // Express middleware
+ * import { agentVisa } from '@agentvisa/verify';
+ * app.use('/api', agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ */
+export { extractToken, verify } from './verify.js';
+export { agentVisa } from './middleware.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @agentvisa/verify — Express middleware
+ */
+import type { Request, Response, NextFunction } from 'express';
+import type { MiddlewareOptions, VerifyResult } from './types.js';
+declare global {
+    namespace Express {
+        interface Request {
+            agentVisa?: VerifyResult & {
+                token: string | null;
+            };
+        }
+    }
+}
+/**
+ * Express middleware that verifies an incoming AgentVisa token.
+ *
+ * Reads the token from AgentVisa-Assertion (Web Bot Auth mode) or
+ * X-AgentVisa-Token (standard mode), calls the AgentVisa API, and
+ * either rejects the request (401) or attaches the result to req.agentVisa.
+ *
+ * @example
+ * // Reject unverified agents immediately
+ * app.use('/api', agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ *
+ * @example
+ * // Flag and decide in your handler
+ * app.use(agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx', onFail: 'flag' }));
+ * app.post('/checkout', (req, res) => {
+ *   if (!req.agentVisa?.valid) return res.status(401).json({ error: 'human_required' });
+ *   // ... proceed
+ * });
+ *
+ * @example
+ * // Web Bot Auth — check binding too
+ * app.use(agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ * app.post('/api', (req, res) => {
+ *   const av = req.agentVisa!;
+ *   // av.valid          → human verified
+ *   // av.webBotAuthBound → token was bound in RFC 9421 signature
+ * });
+ */
+export declare function agentVisa(options: MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGlE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,CAAC,EAAE,YAAY,GAAG;gBAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;aAAE,CAAC;SACrD;KACF;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,iBAAiB,IAIhD,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,KACjB,OAAO,CAAC,IAAI,CAAC,CA+CjB"}

package/dist/middleware.js

@@ -0,0 +1,74 @@
+/**
+ * @agentvisa/verify — Express middleware
+ */
+import { extractToken, verify } from './verify.js';
+/**
+ * Express middleware that verifies an incoming AgentVisa token.
+ *
+ * Reads the token from AgentVisa-Assertion (Web Bot Auth mode) or
+ * X-AgentVisa-Token (standard mode), calls the AgentVisa API, and
+ * either rejects the request (401) or attaches the result to req.agentVisa.
+ *
+ * @example
+ * // Reject unverified agents immediately
+ * app.use('/api', agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ *
+ * @example
+ * // Flag and decide in your handler
+ * app.use(agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx', onFail: 'flag' }));
+ * app.post('/checkout', (req, res) => {
+ *   if (!req.agentVisa?.valid) return res.status(401).json({ error: 'human_required' });
+ *   // ... proceed
+ * });
+ *
+ * @example
+ * // Web Bot Auth — check binding too
+ * app.use(agentVisa({ widgetId: 'wgt_xxx', apiKey: 'wk_xxx' }));
+ * app.post('/api', (req, res) => {
+ *   const av = req.agentVisa!;
+ *   // av.valid          → human verified
+ *   // av.webBotAuthBound → token was bound in RFC 9421 signature
+ * });
+ */
+export function agentVisa(options) {
+    const { onFail = 'reject', rejectBody, ...verifyOptions } = options;
+    return async function agentVisaMiddleware(req, res, next) {
+        const headers = req.headers;
+        const { token } = extractToken(headers);
+        if (!token) {
+            if (onFail === 'flag') {
+                req.agentVisa = {
+                    valid: false,
+                    humanVerified: false,
+                    reason: 'no_token',
+                    token: null,
+                };
+                next();
+                return;
+            }
+            res.status(401).json(rejectBody ?? {
+                error: 'agentvisa_required',
+                message: 'This endpoint requires an AgentVisa token. ' +
+                    'Set AgentVisa-Assertion (Web Bot Auth) or X-AgentVisa-Token header.',
+                widget_id: verifyOptions.widgetId,
+            });
+            return;
+        }
+        const result = await verify(token, verifyOptions, headers);
+        req.agentVisa = { ...result, token };
+        if (!result.valid) {
+            if (onFail === 'flag') {
+                next();
+                return;
+            }
+            res.status(401).json(rejectBody ?? {
+                error: 'agentvisa_invalid',
+                reason: result.reason,
+                message: 'AgentVisa verification failed.',
+            });
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,SAAS,CAAC,OAA0B;IAClD,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,UAAU,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAEpE,OAAO,KAAK,UAAU,mBAAmB,CACvC,GAAY,EACZ,GAAa,EACb,IAAkB;QAElB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAwD,CAAC;QAC7E,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAExC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,GAAG,CAAC,SAAS,GAAG;oBACd,KAAK,EAAE,KAAK;oBACZ,aAAa,EAAE,KAAK;oBACpB,MAAM,EAAE,UAAU;oBAClB,KAAK,EAAE,IAAI;iBACZ,CAAC;gBACF,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAClB,UAAU,IAAI;gBACZ,KAAK,EAAE,oBAAoB;gBAC3B,OAAO,EACL,6CAA6C;oBAC7C,qEAAqE;gBACvE,SAAS,EAAE,aAAa,CAAC,QAAQ;aAClC,CACF,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;QAC3D,GAAG,CAAC,SAAS,GAAG,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC;QAErC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAClB,UAAU,IAAI;gBACZ,KAAK,EAAE,mBAAmB;gBAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,OAAO,EAAE,gCAAgC;aAC1C,CACF,CAAC;YACF,OAAO;QACT,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @agentvisa/verify — TypeScript types
+ */
+export interface VerifyOptions {
+    /** Widget ID from your AgentVisa dashboard (wgt_xxx) */
+    widgetId: string;
+    /** Widget API key from your AgentVisa dashboard (wk_xxx) */
+    apiKey: string;
+    /** Override the AgentVisa API base URL (default: https://api.agentvisa.ai) */
+    apiUrl?: string;
+}
+export interface VerifyResult {
+    /** Whether the AgentVisa token is valid */
+    valid: boolean;
+    /** Whether human verification passed (same as valid — future-proofing) */
+    humanVerified: boolean;
+    /** Reason code from AgentVisa API, or an internal error code */
+    reason: string;
+    /** ISO timestamp of when the human was verified */
+    verifiedAt?: string;
+    /** ISO timestamp of when this token expires */
+    expiresAt?: string;
+    /** Whether the requesting domain is verified by the Widget Holder */
+    domainVerified?: boolean;
+    /**
+     * Whether the AgentVisa-Assertion header was structurally bound in a
+     * Web Bot Auth (RFC 9421) Signature-Input.
+     *
+     * true  = the token was covered by a Web Bot Auth signature (binding is present).
+     *         The WAF/CDN (e.g. Cloudflare) is responsible for verifying the signature itself.
+     * false = token arrived via X-AgentVisa-Token (standard, non-bound mode).
+     * undefined = header inspection was not performed.
+     */
+    webBotAuthBound?: boolean;
+    /** Raw response body from the AgentVisa API */
+    raw?: Record<string, unknown>;
+}
+export interface MiddlewareOptions extends VerifyOptions {
+    /**
+     * What to do when verification fails:
+     *  'reject' — respond 401 immediately (default)
+     *  'flag'   — set req.agentVisa and continue; let your handler decide
+     */
+    onFail?: 'reject' | 'flag';
+    /** Custom 401 response body when onFail = 'reject' */
+    rejectBody?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @agentvisa/verify — TypeScript types
+ */
+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":"AAAA;;GAEG"}

package/dist/verify.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @agentvisa/verify — core verification logic
+ */
+import type { VerifyOptions, VerifyResult } from './types.js';
+type Headers = Record<string, string | string[] | undefined>;
+/**
+ * Extract the AgentVisa token from incoming request headers.
+ *
+ * Checks in order:
+ *  1. AgentVisa-Assertion  — Web Bot Auth mode (token bound in RFC 9421 signature)
+ *  2. X-AgentVisa-Token    — Standard mode
+ *
+ * Returns the token and which header it came from.
+ */
+export declare function extractToken(headers: Headers): {
+    token: string | null;
+    source: 'assertion' | 'header' | null;
+};
+/**
+ * Verify an AgentVisa temporary token against the AgentVisa API.
+ *
+ * @param token    The tmp_xxx token from the agent's request header
+ * @param options  widgetId, apiKey, and optional apiUrl override
+ * @param headers  Full request headers — used to detect Web Bot Auth binding
+ *
+ * @example
+ * // Standalone usage (any framework)
+ * const result = await verify(token, { widgetId, apiKey });
+ * if (!result.valid) return res.status(401).json({ error: result.reason });
+ */
+export declare function verify(token: string, options: VerifyOptions, headers?: Headers): Promise<VerifyResult>;
+export {};
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAuB7D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;CACvC,CAQA;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,YAAY,CAAC,CAqDvB"}

package/dist/verify.js

@@ -0,0 +1,108 @@
+/**
+ * @agentvisa/verify — core verification logic
+ */
+const DEFAULT_API_URL = 'https://api.agentvisa.ai';
+function headerValue(headers, name) {
+    const val = headers[name.toLowerCase()];
+    if (!val)
+        return undefined;
+    return Array.isArray(val) ? val[0] : val;
+}
+/**
+ * Check whether the AgentVisa-Assertion header is covered by a
+ * Web Bot Auth (RFC 9421) Signature-Input.
+ *
+ * This is a structural check — confirms the token was included in the
+ * set of headers the agent signed, but does NOT verify the RFC 9421
+ * signature cryptography. Signature verification is handled by your
+ * WAF/CDN layer (e.g. Cloudflare Web Bot Auth).
+ */
+function isWebBotAuthBound(headers) {
+    const sigInput = headerValue(headers, 'signature-input');
+    if (!sigInput)
+        return false;
+    return sigInput.toLowerCase().includes('"agentvisa-assertion"');
+}
+/**
+ * Extract the AgentVisa token from incoming request headers.
+ *
+ * Checks in order:
+ *  1. AgentVisa-Assertion  — Web Bot Auth mode (token bound in RFC 9421 signature)
+ *  2. X-AgentVisa-Token    — Standard mode
+ *
+ * Returns the token and which header it came from.
+ */
+export function extractToken(headers) {
+    const assertion = headerValue(headers, 'agentvisa-assertion');
+    if (assertion)
+        return { token: assertion, source: 'assertion' };
+    const token = headerValue(headers, 'x-agentvisa-token');
+    if (token)
+        return { token, source: 'header' };
+    return { token: null, source: null };
+}
+/**
+ * Verify an AgentVisa temporary token against the AgentVisa API.
+ *
+ * @param token    The tmp_xxx token from the agent's request header
+ * @param options  widgetId, apiKey, and optional apiUrl override
+ * @param headers  Full request headers — used to detect Web Bot Auth binding
+ *
+ * @example
+ * // Standalone usage (any framework)
+ * const result = await verify(token, { widgetId, apiKey });
+ * if (!result.valid) return res.status(401).json({ error: result.reason });
+ */
+export async function verify(token, options, headers) {
+    const apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '');
+    const webBotAuthBound = headers ? isWebBotAuthBound(headers) : undefined;
+    let response;
+    try {
+        response = await fetch(`${apiUrl}/v1/verify`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Widget-Api-Key': options.apiKey,
+            },
+            body: JSON.stringify({
+                token,
+                widget_id: options.widgetId,
+            }),
+        });
+    }
+    catch (err) {
+        return {
+            valid: false,
+            humanVerified: false,
+            reason: 'network_error',
+            webBotAuthBound,
+            raw: { error: String(err) },
+        };
+    }
+    let data = {};
+    try {
+        data = (await response.json());
+    }
+    catch {
+        // Non-JSON response — treat as error
+        return {
+            valid: false,
+            humanVerified: false,
+            reason: `http_${response.status}`,
+            webBotAuthBound,
+            raw: {},
+        };
+    }
+    const valid = response.ok && data.valid === true;
+    return {
+        valid,
+        humanVerified: valid,
+        reason: data.reason ?? (response.ok ? 'ok' : `http_${response.status}`),
+        verifiedAt: data.verified_at,
+        expiresAt: data.expires_at,
+        domainVerified: data.domain_verified,
+        webBotAuthBound,
+        raw: data,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@agentvisa/verify",
+  "version": "0.1.0",
+  "description": "AgentVisa verifier — verify human-authorized AI agents in one call. Supports Web Bot Auth (RFC 9421) via AgentVisa-Assertion header.",
+  "keywords": [
+    "agentvisa",
+    "web-bot-auth",
+    "rfc9421",
+    "ai-agent",
+    "human-verification",
+    "express",
+    "middleware"
+  ],
+  "homepage": "https://agentvisa.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentVisa-ai/agentvisa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AgentVisa-ai/agentvisa/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}