@verivyx/paywall-hono 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verivyx
+
+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,59 @@
+# @verivyx/paywall-hono
+
+Hono adapter for the Verivyx paywall SDK — gate content from AI bots and charge agents on-chain via x402. Edge-portable: runs on Cloudflare Workers, Vercel Edge Functions, and any Web Platform runtime (no `node:*` imports).
+
+Requires `@verivyx/paywall` (installed automatically as a dependency) and `hono` (peer dependency).
+
+## Install
+
+```sh
+npm i @verivyx/paywall-hono
+```
+
+## Quickstart
+
+```ts
+import { Hono } from "hono";
+import { verivyxHono } from "@verivyx/paywall-hono";
+
+const app = new Hono();
+
+// Create an adapter (reads VERIVYX_TOKEN + VERIVYX_DOMAIN from env)
+const vx = verivyxHono();
+
+// Gate a route — verified/paid requests pass through; bots get a 402
+app.get("/articles/:slug", vx.protect(async (c) => {
+  return c.json({ content: "..." });
+}));
+
+export default app;
+```
+
+### With SEO preview
+
+```ts
+app.get("/articles/:slug", vx.protect(myHandler, {
+  seoPreview: ({ slug }) => ({
+    title: "Article title",
+    excerpt: "A short teaser visible to search crawlers.",
+  }),
+}));
+```
+
+## Config
+
+All options can be passed to `verivyxHono(opts)` or set via environment variables.
+
+| Env var | Required | Description |
+|---|---|---|
+| `VERIVYX_TOKEN` | yes (server-only) | Domain provisioning token from the Verivyx dashboard |
+| `VERIVYX_DOMAIN` | yes | Your site domain, e.g. `example.com` |
+| `VERIVYX_MATCH` | no | Comma-separated glob patterns to gate (e.g. `/articles/**`). Empty = gate all routes. Also accepts `string[]` in code. |
+| `VERIVYX_FAIL_MODE` | no | Behaviour when the Verivyx backend is unreachable: `teaser` (default) \| `open` \| `closed` |
+| `VERIVYX_TIMEOUT_MS` | no | Backend request timeout in milliseconds (default `800`) |
+
+Additional code-only options: `trustProxy` (default `true`, prefers `CF-Connecting-IP`), `advertise` (RSL/AIPREF discovery headers).
+
+## Docs
+
+[https://docs.verivyx.com/docs/sdk](https://docs.verivyx.com/docs/sdk)

package/dist/index.cjs

@@ -0,0 +1,97 @@
+'use strict';
+
+var paywall = require('@verivyx/paywall');
+
+// src/index.ts
+function firstHop(xff) {
+  if (xff === null || xff === void 0 || xff === "") {
+    return void 0;
+  }
+  const first = xff.split(",")[0];
+  return first !== void 0 ? first.trim() || void 0 : void 0;
+}
+function lastPathSegment(pathname) {
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  const last = segments[segments.length - 1];
+  if (last === void 0) {
+    return "";
+  }
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    return last;
+  }
+}
+function resolveIp(c, trustProxy) {
+  if (!trustProxy) {
+    return void 0;
+  }
+  const cfIp = c.req.header("cf-connecting-ip");
+  if (cfIp !== void 0 && cfIp !== "") {
+    return cfIp;
+  }
+  const xff = c.req.header("x-forwarded-for");
+  const hop = firstHop(xff);
+  if (hop !== void 0) {
+    return hop;
+  }
+  const xri = c.req.header("x-real-ip");
+  return xri !== void 0 && xri !== "" ? xri : void 0;
+}
+function withAdvertiseHeaders(res, advertise) {
+  if (advertise === void 0) {
+    return res;
+  }
+  const headers = new Headers(res.headers);
+  headers.append("Link", paywall.rslLinkHeader(advertise));
+  headers.set("Content-Usage", paywall.contentUsageHeader(advertise));
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function verivyxHono(opts) {
+  const vx = opts?._core ?? paywall.verivyx(opts, {
+    verifyCrawlerDns: opts?.verifyCrawlerDns ?? paywall.createSearchCrawlerVerifier(),
+    ...opts?.verifyWebBotAuth !== void 0 ? { verifyWebBotAuth: opts.verifyWebBotAuth } : {}
+  });
+  const trustProxy = opts?.trustProxy !== false;
+  return {
+    protect(handler, o) {
+      return async function verivyxHonoGuard(c) {
+        const raw = c.req.raw;
+        const ip = resolveIp(c, trustProxy);
+        let coreReq;
+        if (ip !== void 0) {
+          const headers = new Headers(raw.headers);
+          headers.set("x-real-ip", ip);
+          coreReq = new Request(raw, { headers });
+        } else {
+          const headers = new Headers(raw.headers);
+          headers.delete("x-real-ip");
+          headers.delete("x-forwarded-for");
+          coreReq = new Request(raw, { headers });
+        }
+        const paramSlug = c.req.param("slug");
+        const slug = paramSlug !== void 0 && paramSlug !== "" ? paramSlug : lastPathSegment(new URL(raw.url).pathname);
+        const decision = await vx.protect(coreReq, { slug });
+        if (!decision.allowed) {
+          const isPreviewCandidate = decision.reason === "crawler" || decision.reason === "human-unverified";
+          if (isPreviewCandidate && o?.seoPreview !== void 0) {
+            return withAdvertiseHeaders(
+              paywall.buildSeoPreviewResponse(slug, raw.url, o.seoPreview),
+              opts?.advertise
+            );
+          }
+          return withAdvertiseHeaders(decision.response(), opts?.advertise);
+        }
+        const res = await handler(c);
+        return withAdvertiseHeaders(
+          paywall.attachPaymentResponse(res, decision.paymentResponse),
+          opts?.advertise
+        );
+      };
+    }
+  };
+}
+
+exports.verivyxHono = verivyxHono;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["rslLinkHeader","contentUsageHeader","verivyx","createSearchCrawlerVerifier","buildSeoPreviewResponse","attachPaymentResponse"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @verivyx/paywall-hono\n *\n * Hono adapter for the Verivyx paywall SDK (Cloudflare Workers / Vercel Edge).\n *\n * Thin layer — all gate logic lives in @verivyx/paywall core.\n * This module handles:\n *   1. IP resolution from Cloudflare / proxy headers (CF-Connecting-IP first).\n *   2. Cloning the Web `Request` with the resolved IP in `x-real-ip`.\n *   3. Calling core `protect()` (decision overload).\n *   4. Returning `decision.response()` when denied (handler NOT called).\n *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.\n *\n * Edge-portable: NO `node:*` imports. Uses only Web Platform APIs and Hono types.\n *\n * @example\n * ```ts\n * import { verivyxHono } from \"@verivyx/paywall-hono\";\n * const vx = verivyxHono({ domain: \"example.com\", token: process.env.VX_TOKEN });\n * app.get(\"/articles/:slug\", vx.protect(async (c) => c.json({ content: \"...\" })));\n * ```\n */\n\nimport {\n  verivyx,\n  createSearchCrawlerVerifier,\n  buildSeoPreviewResponse,\n  attachPaymentResponse,\n  rslLinkHeader,\n  contentUsageHeader,\n} from \"@verivyx/paywall\";\nimport type { VerivyxOptions, Verivyx, DiscoveryOptions } from \"@verivyx/paywall\";\nimport type { Context, MiddlewareHandler } from \"hono\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Hono adapter.\n * Extends core VerivyxOptions with edge-specific controls.\n */\nexport interface HonoAdapterOptions extends VerivyxOptions {\n  /**\n   * When true (default), read the client IP from Cloudflare / proxy headers:\n   *   CF-Connecting-IP → X-Forwarded-For first hop → X-Real-IP.\n   * Set to false if running without a trusted proxy.\n   */\n  trustProxy?: boolean;\n\n  /**\n   * Override the reverse-DNS search-crawler verifier injected into the core.\n   * When omitted, `createSearchCrawlerVerifier()` is used.\n   */\n  verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;\n\n  /**\n   * Override the Web Bot Auth verifier injected into the core.\n   * When omitted, the core's bundled RFC 9421 verifier is used.\n   */\n  verifyWebBotAuth?: (req: Request) => Promise<boolean>;\n\n  /**\n   * @internal\n   * Inject a pre-built `Verivyx` core instance. Used in tests via\n   * `verivyx.mock({...})` to avoid any network access. Production code\n   * should never set this; omit it and the adapter constructs the real core.\n   */\n  _core?: Verivyx;\n\n  /**\n   * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both\n   * the denied (402) and allowed handler responses.\n   * Default undefined = OFF (no headers added; existing behavior unchanged).\n   */\n  advertise?: DiscoveryOptions;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the first (client-most) hop from an `X-Forwarded-For` header value.\n * The header may contain a comma-separated list; the leftmost is the client.\n */\nfunction firstHop(xff: string | null | undefined): string | undefined {\n  if (xff === null || xff === undefined || xff === \"\") {\n    return undefined;\n  }\n  const first = xff.split(\",\")[0];\n  return first !== undefined ? first.trim() || undefined : undefined;\n}\n\n/**\n * Extract the last non-empty path segment from a URL pathname.\n * Used as a fallback slug when `c.req.param(\"slug\")` is unavailable.\n */\nfunction lastPathSegment(pathname: string): string {\n  const segments = pathname.split(\"/\").filter((s) => s.length > 0);\n  const last = segments[segments.length - 1];\n  if (last === undefined) {\n    return \"\";\n  }\n  try {\n    return decodeURIComponent(last);\n  } catch {\n    return last;\n  }\n}\n\n/**\n * Resolve the trusted client IP from Hono context headers.\n *\n * Precedence (Cloudflare Workers best-practice order):\n *   1. CF-Connecting-IP — set by Cloudflare edge (single trusted value).\n *   2. X-Forwarded-For first hop — set by other proxies / Vercel.\n *   3. X-Real-IP — generic proxy header.\n * Returns undefined when trustProxy === false or no header is present.\n */\nfunction resolveIp(c: Context, trustProxy: boolean): string | undefined {\n  if (!trustProxy) {\n    return undefined;\n  }\n  const cfIp = c.req.header(\"cf-connecting-ip\");\n  if (cfIp !== undefined && cfIp !== \"\") {\n    return cfIp;\n  }\n  const xff = c.req.header(\"x-forwarded-for\");\n  const hop = firstHop(xff);\n  if (hop !== undefined) {\n    return hop;\n  }\n  const xri = c.req.header(\"x-real-ip\");\n  return xri !== undefined && xri !== \"\" ? xri : undefined;\n}\n\n/**\n * Attach RSL + AIPREF discovery headers to a Web Response by cloning it.\n * Appends to any existing `Link` (preserves prior values); sets `Content-Usage`.\n * Returns the same Response unchanged when `advertise` is undefined.\n */\nfunction withAdvertiseHeaders(res: Response, advertise: DiscoveryOptions | undefined): Response {\n  if (advertise === undefined) {\n    return res;\n  }\n  const headers = new Headers(res.headers);\n  headers.append(\"Link\", rslLinkHeader(advertise));\n  headers.set(\"Content-Usage\", contentUsageHeader(advertise));\n  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a Verivyx Hono adapter.\n *\n * Returns an object with a single `protect(handler)` method that wraps a\n * Hono route handler behind the Verivyx paywall gate.\n *\n * ```ts\n * const vx = verivyxHono({ domain: \"example.com\", token: \"...\" });\n * app.get(\"/articles/:slug\", vx.protect(async (c) => c.json({ content: \"...\" })));\n * ```\n */\nexport function verivyxHono(opts?: HonoAdapterOptions): {\n  protect(\n    handler: (c: Context) => Response | Promise<Response>,\n    o?: { seoPreview?: (c: { slug: string }) => { title: string; excerpt: string } },\n  ): MiddlewareHandler;\n} {\n  // Resolve the core: use the injected `_core` (tests) or build the real one.\n  // Only pass `verifyWebBotAuth` to the core deps when the caller overrode it;\n  // the core bundled default is correct otherwise.\n  const vx: Verivyx =\n    opts?._core ??\n    verivyx(opts, {\n      verifyCrawlerDns:\n        opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),\n      ...(opts?.verifyWebBotAuth !== undefined\n        ? { verifyWebBotAuth: opts.verifyWebBotAuth }\n        : {}),\n    });\n\n  const trustProxy = opts?.trustProxy !== false; // default true\n\n  return {\n    protect(\n      handler: (c: Context) => Response | Promise<Response>,\n      o?: { seoPreview?: (c: { slug: string }) => { title: string; excerpt: string } },\n    ): MiddlewareHandler {\n      return async function verivyxHonoGuard(c): Promise<Response> {\n        // 1. Get the raw Web Request from Hono context.\n        const raw = c.req.raw;\n\n        // 2. Resolve trusted client IP and inject into a cloned request so the\n        //    core classifier reads a reliable address regardless of edge hop.\n        //\n        //    Security invariant:\n        //      trustProxy !== false → resolve IP from CF/proxy headers and set\n        //        x-real-ip on the cloned request (overrides any client value).\n        //      trustProxy === false  → no socket IP is available in edge runtimes;\n        //        strip both x-real-ip and x-forwarded-for so a client cannot\n        //        spoof an IP into the core classifier (core sees no IP → safe).\n        const ip = resolveIp(c, trustProxy);\n        let coreReq: Request;\n        if (ip !== undefined) {\n          const headers = new Headers(raw.headers);\n          headers.set(\"x-real-ip\", ip);\n          // Clone the Request with updated headers. For GET/HEAD this is safe;\n          // the core classify path reads headers only — body stays with raw.\n          coreReq = new Request(raw, { headers });\n        } else {\n          // trustProxy === false: strip forwarding headers so the client cannot\n          // inject a spoofed IP into the core.\n          const headers = new Headers(raw.headers);\n          headers.delete(\"x-real-ip\");\n          headers.delete(\"x-forwarded-for\");\n          coreReq = new Request(raw, { headers });\n        }\n\n        // 3. Resolve slug.\n        //    Priority: Hono named param \"slug\" > last URL path segment.\n        const paramSlug: string | undefined = c.req.param(\"slug\");\n        const slug: string =\n          (paramSlug !== undefined && paramSlug !== \"\")\n            ? paramSlug\n            : lastPathSegment(new URL(raw.url).pathname);\n\n        // 4. Ask the core to evaluate the request (decision overload).\n        const decision = await vx.protect(coreReq, { slug });\n\n        // 5. Denied — check if this is a crawler/human-unverified that we can\n        //    serve an SEO preview to instead of a bare 402. Handler NOT called.\n        if (!decision.allowed) {\n          const isPreviewCandidate =\n            decision.reason === \"crawler\" || decision.reason === \"human-unverified\";\n          if (isPreviewCandidate && o?.seoPreview !== undefined) {\n            return withAdvertiseHeaders(\n              buildSeoPreviewResponse(slug, raw.url, o.seoPreview),\n              opts?.advertise,\n            );\n          }\n          return withAdvertiseHeaders(decision.response(), opts?.advertise);\n        }\n\n        // 6. Allowed — call the original Hono handler.\n        const res = await handler(c);\n\n        // 7. Attach the settlement receipt header when a payment was processed,\n        //    then attach discovery headers (single clone when both apply).\n        return withAdvertiseHeaders(\n          attachPaymentResponse(res, decision.paymentResponse),\n          opts?.advertise,\n        );\n      };\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+import { VerivyxOptions, Verivyx, DiscoveryOptions } from '@verivyx/paywall';
+import { Context, MiddlewareHandler } from 'hono';
+
+/**
+ * @verivyx/paywall-hono
+ *
+ * Hono adapter for the Verivyx paywall SDK (Cloudflare Workers / Vercel Edge).
+ *
+ * Thin layer — all gate logic lives in @verivyx/paywall core.
+ * This module handles:
+ *   1. IP resolution from Cloudflare / proxy headers (CF-Connecting-IP first).
+ *   2. Cloning the Web `Request` with the resolved IP in `x-real-ip`.
+ *   3. Calling core `protect()` (decision overload).
+ *   4. Returning `decision.response()` when denied (handler NOT called).
+ *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.
+ *
+ * Edge-portable: NO `node:*` imports. Uses only Web Platform APIs and Hono types.
+ *
+ * @example
+ * ```ts
+ * import { verivyxHono } from "@verivyx/paywall-hono";
+ * const vx = verivyxHono({ domain: "example.com", token: process.env.VX_TOKEN });
+ * app.get("/articles/:slug", vx.protect(async (c) => c.json({ content: "..." })));
+ * ```
+ */
+
+/**
+ * Options for the Hono adapter.
+ * Extends core VerivyxOptions with edge-specific controls.
+ */
+interface HonoAdapterOptions extends VerivyxOptions {
+    /**
+     * When true (default), read the client IP from Cloudflare / proxy headers:
+     *   CF-Connecting-IP → X-Forwarded-For first hop → X-Real-IP.
+     * Set to false if running without a trusted proxy.
+     */
+    trustProxy?: boolean;
+    /**
+     * Override the reverse-DNS search-crawler verifier injected into the core.
+     * When omitted, `createSearchCrawlerVerifier()` is used.
+     */
+    verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;
+    /**
+     * Override the Web Bot Auth verifier injected into the core.
+     * When omitted, the core's bundled RFC 9421 verifier is used.
+     */
+    verifyWebBotAuth?: (req: Request) => Promise<boolean>;
+    /**
+     * @internal
+     * Inject a pre-built `Verivyx` core instance. Used in tests via
+     * `verivyx.mock({...})` to avoid any network access. Production code
+     * should never set this; omit it and the adapter constructs the real core.
+     */
+    _core?: Verivyx;
+    /**
+     * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both
+     * the denied (402) and allowed handler responses.
+     * Default undefined = OFF (no headers added; existing behavior unchanged).
+     */
+    advertise?: DiscoveryOptions;
+}
+/**
+ * Create a Verivyx Hono adapter.
+ *
+ * Returns an object with a single `protect(handler)` method that wraps a
+ * Hono route handler behind the Verivyx paywall gate.
+ *
+ * ```ts
+ * const vx = verivyxHono({ domain: "example.com", token: "..." });
+ * app.get("/articles/:slug", vx.protect(async (c) => c.json({ content: "..." })));
+ * ```
+ */
+declare function verivyxHono(opts?: HonoAdapterOptions): {
+    protect(handler: (c: Context) => Response | Promise<Response>, o?: {
+        seoPreview?: (c: {
+            slug: string;
+        }) => {
+            title: string;
+            excerpt: string;
+        };
+    }): MiddlewareHandler;
+};
+
+export { type HonoAdapterOptions, verivyxHono };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { VerivyxOptions, Verivyx, DiscoveryOptions } from '@verivyx/paywall';
+import { Context, MiddlewareHandler } from 'hono';
+
+/**
+ * @verivyx/paywall-hono
+ *
+ * Hono adapter for the Verivyx paywall SDK (Cloudflare Workers / Vercel Edge).
+ *
+ * Thin layer — all gate logic lives in @verivyx/paywall core.
+ * This module handles:
+ *   1. IP resolution from Cloudflare / proxy headers (CF-Connecting-IP first).
+ *   2. Cloning the Web `Request` with the resolved IP in `x-real-ip`.
+ *   3. Calling core `protect()` (decision overload).
+ *   4. Returning `decision.response()` when denied (handler NOT called).
+ *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.
+ *
+ * Edge-portable: NO `node:*` imports. Uses only Web Platform APIs and Hono types.
+ *
+ * @example
+ * ```ts
+ * import { verivyxHono } from "@verivyx/paywall-hono";
+ * const vx = verivyxHono({ domain: "example.com", token: process.env.VX_TOKEN });
+ * app.get("/articles/:slug", vx.protect(async (c) => c.json({ content: "..." })));
+ * ```
+ */
+
+/**
+ * Options for the Hono adapter.
+ * Extends core VerivyxOptions with edge-specific controls.
+ */
+interface HonoAdapterOptions extends VerivyxOptions {
+    /**
+     * When true (default), read the client IP from Cloudflare / proxy headers:
+     *   CF-Connecting-IP → X-Forwarded-For first hop → X-Real-IP.
+     * Set to false if running without a trusted proxy.
+     */
+    trustProxy?: boolean;
+    /**
+     * Override the reverse-DNS search-crawler verifier injected into the core.
+     * When omitted, `createSearchCrawlerVerifier()` is used.
+     */
+    verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;
+    /**
+     * Override the Web Bot Auth verifier injected into the core.
+     * When omitted, the core's bundled RFC 9421 verifier is used.
+     */
+    verifyWebBotAuth?: (req: Request) => Promise<boolean>;
+    /**
+     * @internal
+     * Inject a pre-built `Verivyx` core instance. Used in tests via
+     * `verivyx.mock({...})` to avoid any network access. Production code
+     * should never set this; omit it and the adapter constructs the real core.
+     */
+    _core?: Verivyx;
+    /**
+     * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both
+     * the denied (402) and allowed handler responses.
+     * Default undefined = OFF (no headers added; existing behavior unchanged).
+     */
+    advertise?: DiscoveryOptions;
+}
+/**
+ * Create a Verivyx Hono adapter.
+ *
+ * Returns an object with a single `protect(handler)` method that wraps a
+ * Hono route handler behind the Verivyx paywall gate.
+ *
+ * ```ts
+ * const vx = verivyxHono({ domain: "example.com", token: "..." });
+ * app.get("/articles/:slug", vx.protect(async (c) => c.json({ content: "..." })));
+ * ```
+ */
+declare function verivyxHono(opts?: HonoAdapterOptions): {
+    protect(handler: (c: Context) => Response | Promise<Response>, o?: {
+        seoPreview?: (c: {
+            slug: string;
+        }) => {
+            title: string;
+            excerpt: string;
+        };
+    }): MiddlewareHandler;
+};
+
+export { type HonoAdapterOptions, verivyxHono };

package/dist/index.js

@@ -0,0 +1,95 @@
+import { verivyx, createSearchCrawlerVerifier, buildSeoPreviewResponse, attachPaymentResponse, rslLinkHeader, contentUsageHeader } from '@verivyx/paywall';
+
+// src/index.ts
+function firstHop(xff) {
+  if (xff === null || xff === void 0 || xff === "") {
+    return void 0;
+  }
+  const first = xff.split(",")[0];
+  return first !== void 0 ? first.trim() || void 0 : void 0;
+}
+function lastPathSegment(pathname) {
+  const segments = pathname.split("/").filter((s) => s.length > 0);
+  const last = segments[segments.length - 1];
+  if (last === void 0) {
+    return "";
+  }
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    return last;
+  }
+}
+function resolveIp(c, trustProxy) {
+  if (!trustProxy) {
+    return void 0;
+  }
+  const cfIp = c.req.header("cf-connecting-ip");
+  if (cfIp !== void 0 && cfIp !== "") {
+    return cfIp;
+  }
+  const xff = c.req.header("x-forwarded-for");
+  const hop = firstHop(xff);
+  if (hop !== void 0) {
+    return hop;
+  }
+  const xri = c.req.header("x-real-ip");
+  return xri !== void 0 && xri !== "" ? xri : void 0;
+}
+function withAdvertiseHeaders(res, advertise) {
+  if (advertise === void 0) {
+    return res;
+  }
+  const headers = new Headers(res.headers);
+  headers.append("Link", rslLinkHeader(advertise));
+  headers.set("Content-Usage", contentUsageHeader(advertise));
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function verivyxHono(opts) {
+  const vx = opts?._core ?? verivyx(opts, {
+    verifyCrawlerDns: opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),
+    ...opts?.verifyWebBotAuth !== void 0 ? { verifyWebBotAuth: opts.verifyWebBotAuth } : {}
+  });
+  const trustProxy = opts?.trustProxy !== false;
+  return {
+    protect(handler, o) {
+      return async function verivyxHonoGuard(c) {
+        const raw = c.req.raw;
+        const ip = resolveIp(c, trustProxy);
+        let coreReq;
+        if (ip !== void 0) {
+          const headers = new Headers(raw.headers);
+          headers.set("x-real-ip", ip);
+          coreReq = new Request(raw, { headers });
+        } else {
+          const headers = new Headers(raw.headers);
+          headers.delete("x-real-ip");
+          headers.delete("x-forwarded-for");
+          coreReq = new Request(raw, { headers });
+        }
+        const paramSlug = c.req.param("slug");
+        const slug = paramSlug !== void 0 && paramSlug !== "" ? paramSlug : lastPathSegment(new URL(raw.url).pathname);
+        const decision = await vx.protect(coreReq, { slug });
+        if (!decision.allowed) {
+          const isPreviewCandidate = decision.reason === "crawler" || decision.reason === "human-unverified";
+          if (isPreviewCandidate && o?.seoPreview !== void 0) {
+            return withAdvertiseHeaders(
+              buildSeoPreviewResponse(slug, raw.url, o.seoPreview),
+              opts?.advertise
+            );
+          }
+          return withAdvertiseHeaders(decision.response(), opts?.advertise);
+        }
+        const res = await handler(c);
+        return withAdvertiseHeaders(
+          attachPaymentResponse(res, decision.paymentResponse),
+          opts?.advertise
+        );
+      };
+    }
+  };
+}
+
+export { verivyxHono };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @verivyx/paywall-hono\n *\n * Hono adapter for the Verivyx paywall SDK (Cloudflare Workers / Vercel Edge).\n *\n * Thin layer — all gate logic lives in @verivyx/paywall core.\n * This module handles:\n *   1. IP resolution from Cloudflare / proxy headers (CF-Connecting-IP first).\n *   2. Cloning the Web `Request` with the resolved IP in `x-real-ip`.\n *   3. Calling core `protect()` (decision overload).\n *   4. Returning `decision.response()` when denied (handler NOT called).\n *   5. Attaching `PAYMENT-RESPONSE` header when a settlement receipt exists.\n *\n * Edge-portable: NO `node:*` imports. Uses only Web Platform APIs and Hono types.\n *\n * @example\n * ```ts\n * import { verivyxHono } from \"@verivyx/paywall-hono\";\n * const vx = verivyxHono({ domain: \"example.com\", token: process.env.VX_TOKEN });\n * app.get(\"/articles/:slug\", vx.protect(async (c) => c.json({ content: \"...\" })));\n * ```\n */\n\nimport {\n  verivyx,\n  createSearchCrawlerVerifier,\n  buildSeoPreviewResponse,\n  attachPaymentResponse,\n  rslLinkHeader,\n  contentUsageHeader,\n} from \"@verivyx/paywall\";\nimport type { VerivyxOptions, Verivyx, DiscoveryOptions } from \"@verivyx/paywall\";\nimport type { Context, MiddlewareHandler } from \"hono\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Hono adapter.\n * Extends core VerivyxOptions with edge-specific controls.\n */\nexport interface HonoAdapterOptions extends VerivyxOptions {\n  /**\n   * When true (default), read the client IP from Cloudflare / proxy headers:\n   *   CF-Connecting-IP → X-Forwarded-For first hop → X-Real-IP.\n   * Set to false if running without a trusted proxy.\n   */\n  trustProxy?: boolean;\n\n  /**\n   * Override the reverse-DNS search-crawler verifier injected into the core.\n   * When omitted, `createSearchCrawlerVerifier()` is used.\n   */\n  verifyCrawlerDns?: (ip: string, ua: string) => Promise<boolean>;\n\n  /**\n   * Override the Web Bot Auth verifier injected into the core.\n   * When omitted, the core's bundled RFC 9421 verifier is used.\n   */\n  verifyWebBotAuth?: (req: Request) => Promise<boolean>;\n\n  /**\n   * @internal\n   * Inject a pre-built `Verivyx` core instance. Used in tests via\n   * `verivyx.mock({...})` to avoid any network access. Production code\n   * should never set this; omit it and the adapter constructs the real core.\n   */\n  _core?: Verivyx;\n\n  /**\n   * When set, attach RSL `Link` and AIPREF `Content-Usage` headers to both\n   * the denied (402) and allowed handler responses.\n   * Default undefined = OFF (no headers added; existing behavior unchanged).\n   */\n  advertise?: DiscoveryOptions;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract the first (client-most) hop from an `X-Forwarded-For` header value.\n * The header may contain a comma-separated list; the leftmost is the client.\n */\nfunction firstHop(xff: string | null | undefined): string | undefined {\n  if (xff === null || xff === undefined || xff === \"\") {\n    return undefined;\n  }\n  const first = xff.split(\",\")[0];\n  return first !== undefined ? first.trim() || undefined : undefined;\n}\n\n/**\n * Extract the last non-empty path segment from a URL pathname.\n * Used as a fallback slug when `c.req.param(\"slug\")` is unavailable.\n */\nfunction lastPathSegment(pathname: string): string {\n  const segments = pathname.split(\"/\").filter((s) => s.length > 0);\n  const last = segments[segments.length - 1];\n  if (last === undefined) {\n    return \"\";\n  }\n  try {\n    return decodeURIComponent(last);\n  } catch {\n    return last;\n  }\n}\n\n/**\n * Resolve the trusted client IP from Hono context headers.\n *\n * Precedence (Cloudflare Workers best-practice order):\n *   1. CF-Connecting-IP — set by Cloudflare edge (single trusted value).\n *   2. X-Forwarded-For first hop — set by other proxies / Vercel.\n *   3. X-Real-IP — generic proxy header.\n * Returns undefined when trustProxy === false or no header is present.\n */\nfunction resolveIp(c: Context, trustProxy: boolean): string | undefined {\n  if (!trustProxy) {\n    return undefined;\n  }\n  const cfIp = c.req.header(\"cf-connecting-ip\");\n  if (cfIp !== undefined && cfIp !== \"\") {\n    return cfIp;\n  }\n  const xff = c.req.header(\"x-forwarded-for\");\n  const hop = firstHop(xff);\n  if (hop !== undefined) {\n    return hop;\n  }\n  const xri = c.req.header(\"x-real-ip\");\n  return xri !== undefined && xri !== \"\" ? xri : undefined;\n}\n\n/**\n * Attach RSL + AIPREF discovery headers to a Web Response by cloning it.\n * Appends to any existing `Link` (preserves prior values); sets `Content-Usage`.\n * Returns the same Response unchanged when `advertise` is undefined.\n */\nfunction withAdvertiseHeaders(res: Response, advertise: DiscoveryOptions | undefined): Response {\n  if (advertise === undefined) {\n    return res;\n  }\n  const headers = new Headers(res.headers);\n  headers.append(\"Link\", rslLinkHeader(advertise));\n  headers.set(\"Content-Usage\", contentUsageHeader(advertise));\n  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });\n}\n\n// ---------------------------------------------------------------------------\n// Adapter factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a Verivyx Hono adapter.\n *\n * Returns an object with a single `protect(handler)` method that wraps a\n * Hono route handler behind the Verivyx paywall gate.\n *\n * ```ts\n * const vx = verivyxHono({ domain: \"example.com\", token: \"...\" });\n * app.get(\"/articles/:slug\", vx.protect(async (c) => c.json({ content: \"...\" })));\n * ```\n */\nexport function verivyxHono(opts?: HonoAdapterOptions): {\n  protect(\n    handler: (c: Context) => Response | Promise<Response>,\n    o?: { seoPreview?: (c: { slug: string }) => { title: string; excerpt: string } },\n  ): MiddlewareHandler;\n} {\n  // Resolve the core: use the injected `_core` (tests) or build the real one.\n  // Only pass `verifyWebBotAuth` to the core deps when the caller overrode it;\n  // the core bundled default is correct otherwise.\n  const vx: Verivyx =\n    opts?._core ??\n    verivyx(opts, {\n      verifyCrawlerDns:\n        opts?.verifyCrawlerDns ?? createSearchCrawlerVerifier(),\n      ...(opts?.verifyWebBotAuth !== undefined\n        ? { verifyWebBotAuth: opts.verifyWebBotAuth }\n        : {}),\n    });\n\n  const trustProxy = opts?.trustProxy !== false; // default true\n\n  return {\n    protect(\n      handler: (c: Context) => Response | Promise<Response>,\n      o?: { seoPreview?: (c: { slug: string }) => { title: string; excerpt: string } },\n    ): MiddlewareHandler {\n      return async function verivyxHonoGuard(c): Promise<Response> {\n        // 1. Get the raw Web Request from Hono context.\n        const raw = c.req.raw;\n\n        // 2. Resolve trusted client IP and inject into a cloned request so the\n        //    core classifier reads a reliable address regardless of edge hop.\n        //\n        //    Security invariant:\n        //      trustProxy !== false → resolve IP from CF/proxy headers and set\n        //        x-real-ip on the cloned request (overrides any client value).\n        //      trustProxy === false  → no socket IP is available in edge runtimes;\n        //        strip both x-real-ip and x-forwarded-for so a client cannot\n        //        spoof an IP into the core classifier (core sees no IP → safe).\n        const ip = resolveIp(c, trustProxy);\n        let coreReq: Request;\n        if (ip !== undefined) {\n          const headers = new Headers(raw.headers);\n          headers.set(\"x-real-ip\", ip);\n          // Clone the Request with updated headers. For GET/HEAD this is safe;\n          // the core classify path reads headers only — body stays with raw.\n          coreReq = new Request(raw, { headers });\n        } else {\n          // trustProxy === false: strip forwarding headers so the client cannot\n          // inject a spoofed IP into the core.\n          const headers = new Headers(raw.headers);\n          headers.delete(\"x-real-ip\");\n          headers.delete(\"x-forwarded-for\");\n          coreReq = new Request(raw, { headers });\n        }\n\n        // 3. Resolve slug.\n        //    Priority: Hono named param \"slug\" > last URL path segment.\n        const paramSlug: string | undefined = c.req.param(\"slug\");\n        const slug: string =\n          (paramSlug !== undefined && paramSlug !== \"\")\n            ? paramSlug\n            : lastPathSegment(new URL(raw.url).pathname);\n\n        // 4. Ask the core to evaluate the request (decision overload).\n        const decision = await vx.protect(coreReq, { slug });\n\n        // 5. Denied — check if this is a crawler/human-unverified that we can\n        //    serve an SEO preview to instead of a bare 402. Handler NOT called.\n        if (!decision.allowed) {\n          const isPreviewCandidate =\n            decision.reason === \"crawler\" || decision.reason === \"human-unverified\";\n          if (isPreviewCandidate && o?.seoPreview !== undefined) {\n            return withAdvertiseHeaders(\n              buildSeoPreviewResponse(slug, raw.url, o.seoPreview),\n              opts?.advertise,\n            );\n          }\n          return withAdvertiseHeaders(decision.response(), opts?.advertise);\n        }\n\n        // 6. Allowed — call the original Hono handler.\n        const res = await handler(c);\n\n        // 7. Attach the settlement receipt header when a payment was processed,\n        //    then attach discovery headers (single clone when both apply).\n        return withAdvertiseHeaders(\n          attachPaymentResponse(res, decision.paymentResponse),\n          opts?.advertise,\n        );\n      };\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@verivyx/paywall-hono",
+  "version": "0.1.0",
+  "description": "Hono adapter for the Verivyx paywall SDK (Cloudflare Workers / Vercel Edge)",
+  "type": "module",
+  "license": "MIT",
+  "author": "Verivyx",
+  "sideEffects": false,
+  "keywords": ["paywall", "x402", "ai", "bot", "stellar", "verivyx"],
+  "homepage": "https://docs.verivyx.com/docs/sdk",
+  "bugs": { "url": "https://github.com/VerivyX/verivyx-monorepo/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VerivyX/verivyx-monorepo.git",
+    "directory": "services/publisher-sdk/packages/hono"
+  },
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@verivyx/paywall": "^0.1.0"
+  },
+  "peerDependencies": {
+    "hono": ">=4"
+  },
+  "devDependencies": {
+    "hono": "^4.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}