@btx-tools/middleware-hono 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 visitor-code
+
+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,119 @@
+# @btx-tools/middleware-hono
+
+Drop-in **Hono** admission gate backed by BTX service challenges. Works on Node, Deno, Bun, **Cloudflare Workers**, and other edge runtimes Hono targets. Same flow + ergonomics as [`@btx-tools/middleware-express`](https://www.npmjs.com/package/@btx-tools/middleware-express) and [`@btx-tools/middleware-fastify`](https://www.npmjs.com/package/@btx-tools/middleware-fastify), tailored to Hono's middleware model + `c.set('btx', ...)` variables.
+
+```bash
+pnpm add @btx-tools/middleware-hono @btx-tools/challenges-sdk hono
+```
+
+## Quickstart
+
+```ts
+import { Hono } from 'hono';
+import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+import { btxAdmission, type BtxAdmissionVariables } from '@btx-tools/middleware-hono';
+
+const client = new BtxChallengeClient({
+  rpcUrl: 'http://127.0.0.1:19334',
+  rpcAuth: { user: 'rpcuser', pass: 'rpcpass' },
+});
+
+const app = new Hono<{ Variables: BtxAdmissionVariables }>();
+
+app.post('/v1/generate',
+  btxAdmission({
+    client,
+    purpose: 'ai_inference_gate',
+    resource: (c) => `route:${c.req.path}`,
+    subject: async (c) => `tenant:${(await c.req.json()).tenant_id}`,
+    issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+    onError: (err, c) => c.var.logger?.error({ err }, 'btx admission error'),
+  }),
+  async (c) => {
+    const admit = c.get('btx').result;
+    return c.json({ ok: true, reason: admit.reason });
+  },
+);
+
+export default app;
+```
+
+## How it works
+
+Stateless **echo-the-challenge** flow:
+
+1. **First request** has no proof headers → middleware calls `client.issue()` → replies `402 Payment Required` with `X-BTX-Challenge` header containing the challenge JSON + a body listing the headers the client should add on retry.
+2. **Client solves** the challenge (locally or via RPC) and **retries** with `X-BTX-Challenge` (echoed), `X-BTX-Proof-Nonce`, `X-BTX-Proof-Digest`.
+3. Middleware calls `client.redeem()` → if `result.valid === true`, sets `c.set('btx', { result })` and yields to `await next()` (route handler runs). Else replies `403`.
+
+No server-side challenge store. Scales horizontally; the challenge JSON rides in the `X-BTX-Challenge` header on retry (~3-5 KB). Check edge-runtime header-size limits — Cloudflare Workers and Fastly accept large headers, but Vercel Edge caps at smaller sizes.
+
+## API
+
+### `btxAdmission(opts): MiddlewareHandler`
+
+Returns a Hono middleware function to attach per-route.
+
+#### Options
+
+| Field | Type | Notes |
+|---|---|---|
+| `client` | `BtxChallengeClient` | required. Construct once at boot. |
+| `purpose` | `string \| (c) => string \| (c) => Promise<string>` | required. Logical purpose label. Async resolver supported so you can `await c.req.json()`. |
+| `resource` | `string \| (c) => string \| (c) => Promise<string>` | required. |
+| `subject` | `string \| (c) => string \| (c) => Promise<string>` | required. |
+| `issueParams` | `Partial<IssueParams>` | optional. |
+| `onAdmit` | `(c, result) => void` | optional. Fires on successful admission. |
+| `onError` | `(err, c) => void` | optional. Fires when `client.issue()` or `client.redeem()` throws. Re-thrown to Hono's `onError`. Audit ref: D-1. |
+| `isProofPresent` | `(c) => boolean` | optional. Predicate override. |
+
+### `BtxAdmissionVariables`
+
+Type the Hono instance with this for `c.get('btx')` type narrowing:
+
+```ts
+const app = new Hono<{ Variables: BtxAdmissionVariables }>();
+```
+
+After admission, `c.get('btx')` is `{ result: VerifyResult } | undefined`.
+
+### Header constants
+
+| Constant | Value |
+|---|---|
+| `HEADER_CHALLENGE` | `'x-btx-challenge'` |
+| `HEADER_CHALLENGE_ID` | `'x-btx-challenge-id'` |
+| `HEADER_PROOF_NONCE` | `'x-btx-proof-nonce'` |
+| `HEADER_PROOF_DIGEST` | `'x-btx-proof-digest'` |
+
+## Error handling
+
+When `client.issue()` or `client.redeem()` throws (e.g., btxd RPC down, network error), the middleware:
+1. Calls `opts.onError(err, c)` if provided
+2. Re-throws — Hono's `app.onError()` handler kicks in
+
+Use `app.onError()` to map BTX errors to your preferred response shape:
+
+```ts
+app.onError((err, c) => {
+  if (err instanceof BtxNetworkError) return c.json({ error: 'btxd unreachable' }, 503);
+  return c.json({ error: 'internal' }, 500);
+});
+```
+
+## Edge-runtime notes
+
+- **Cloudflare Workers / Pages**: works out of the box. `BtxChallengeClient` uses `fetch()` which is the native Workers networking primitive.
+- **Deno Deploy**: same — `fetch()` is standard.
+- **Bun**: same.
+- **Vercel Edge**: works, but check max header size (Vercel Edge caps incoming headers around 16 KB). For high-difficulty challenges the JSON envelope might exceed this — consider switching to a stateful challenge-store middleware variant if you hit this.
+
+## Requirements
+
+- **Node.js** ≥ 18.17 (when running on Node)
+- **Hono** ^4.0.0 (peer dep)
+- **@btx-tools/challenges-sdk** ^0.0.4 (peer dep)
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+// src/index.ts
+var HEADER_CHALLENGE = "x-btx-challenge";
+var HEADER_CHALLENGE_ID = "x-btx-challenge-id";
+var HEADER_PROOF_NONCE = "x-btx-proof-nonce";
+var HEADER_PROOF_DIGEST = "x-btx-proof-digest";
+function btxAdmission(opts) {
+  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;
+  return async function btxAdmissionMiddleware(c, next) {
+    if (!proofPresent(c)) {
+      return issueAndRespond(c, opts);
+    }
+    return redeemAndAdmit(c, next, opts);
+  };
+}
+function defaultIsProofPresent(c) {
+  return Boolean(
+    c.req.header(HEADER_CHALLENGE) && c.req.header(HEADER_PROOF_NONCE) && c.req.header(HEADER_PROOF_DIGEST)
+  );
+}
+async function issueAndRespond(c, opts) {
+  try {
+    const purpose = await resolve(opts.purpose, c);
+    const resource = await resolve(opts.resource, c);
+    const subject = await resolve(opts.subject, c);
+    const challenge = await opts.client.issue({
+      purpose,
+      resource,
+      subject,
+      ...opts.issueParams
+    });
+    c.header(HEADER_CHALLENGE, JSON.stringify(challenge));
+    return c.json(
+      {
+        challenge,
+        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST]
+      },
+      402
+    );
+  } catch (err) {
+    opts.onError?.(err, c);
+    throw err;
+  }
+}
+async function redeemAndAdmit(c, next, opts) {
+  const challengeRaw = c.req.header(HEADER_CHALLENGE);
+  const nonce = c.req.header(HEADER_PROOF_NONCE);
+  const digest = c.req.header(HEADER_PROOF_DIGEST);
+  if (!challengeRaw) {
+    return c.json(
+      {
+        error: "missing_challenge_header",
+        message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`
+      },
+      400
+    );
+  }
+  let challenge;
+  try {
+    challenge = JSON.parse(challengeRaw);
+  } catch {
+    return c.json(
+      {
+        error: "malformed_challenge_header",
+        message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`
+      },
+      400
+    );
+  }
+  const idHeader = c.req.header(HEADER_CHALLENGE_ID);
+  if (idHeader && idHeader !== challenge.challenge_id) {
+    return c.json(
+      {
+        error: "challenge_id_mismatch",
+        message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`
+      },
+      400
+    );
+  }
+  try {
+    const result = await opts.client.redeem(challenge, nonce, digest);
+    if (!result.valid) {
+      return c.json(
+        {
+          valid: false,
+          reason: result.reason,
+          expired: result.expired
+        },
+        403
+      );
+    }
+    c.set("btx", { result });
+    opts.onAdmit?.(c, result);
+    await next();
+    return;
+  } catch (err) {
+    opts.onError?.(err, c);
+    throw err;
+  }
+}
+async function resolve(value, c) {
+  if (typeof value === "function") {
+    return await value(c);
+  }
+  return value;
+}
+
+exports.HEADER_CHALLENGE = HEADER_CHALLENGE;
+exports.HEADER_CHALLENGE_ID = HEADER_CHALLENGE_ID;
+exports.HEADER_PROOF_DIGEST = HEADER_PROOF_DIGEST;
+exports.HEADER_PROOF_NONCE = HEADER_PROOF_NONCE;
+exports.btxAdmission = btxAdmission;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @btx-tools/middleware-hono\n *\n * Drop-in **Hono** admission gate backed by BTX service challenges.\n * Mirrors the behavior of `@btx-tools/middleware-express` and\n * `@btx-tools/middleware-fastify` for Hono's middleware model — works on\n * Node, Deno, Bun, Cloudflare Workers, and other edge runtimes Hono targets.\n *\n * Flow (stateless, echo-the-challenge):\n *\n *   client → POST /v1/generate                          (no proof headers)\n *   server →   402 Payment Required\n *              X-BTX-Challenge: <stringified challenge JSON>\n *              body: { challenge, retry_with: [...] }\n *\n *   client solves locally (or via RPC), retries:\n *   client → POST /v1/generate\n *              X-BTX-Challenge: <echoed challenge JSON>\n *              X-BTX-Challenge-Id: <id>             (optional sanity check)\n *              X-BTX-Proof-Nonce: <hex>\n *              X-BTX-Proof-Digest: <hex>\n *   server →   200 OK  (handler runs; c.get('btx').result is the VerifyResult)\n *\n *   Invalid proof → 403 with { valid: false, reason }.\n *   btxd RPC error → throws — Hono's onError handler catches it.\n *\n * Usage (per-route):\n * ```ts\n * import { Hono } from 'hono';\n * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';\n * import { btxAdmission } from '@btx-tools/middleware-hono';\n *\n * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });\n * const app = new Hono<{ Variables: { btx: { result: import('@btx-tools/challenges-sdk').VerifyResult } } }>();\n *\n * app.post('/v1/generate',\n *   btxAdmission({\n *     client,\n *     purpose: 'ai_inference_gate',\n *     resource: (c) => `route:${c.req.path}`,\n *     subject: async (c) => `tenant:${(await c.req.json()).tenant_id}`,\n *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },\n *   }),\n *   async (c) => {\n *     const admit = c.get('btx').result;\n *     return c.json({ ok: true, reason: admit.reason });\n *   },\n * );\n * ```\n */\n\nimport type { Context, MiddlewareHandler } from 'hono';\n\nimport type {\n  BtxChallengeClient,\n  Challenge,\n  IssueParams,\n  VerifyResult,\n} from '@btx-tools/challenges-sdk';\n\n// ----------------------------------------------------------------------------\n// Public constants\n// ----------------------------------------------------------------------------\n\nexport const HEADER_CHALLENGE = 'x-btx-challenge';\nexport const HEADER_CHALLENGE_ID = 'x-btx-challenge-id';\nexport const HEADER_PROOF_NONCE = 'x-btx-proof-nonce';\nexport const HEADER_PROOF_DIGEST = 'x-btx-proof-digest';\n// Note: Web standard Headers (which Hono uses) are case-insensitive on get but\n// typically lowercased internally. Use lowercase names to keep consistent.\n\n// ----------------------------------------------------------------------------\n// Types\n// ----------------------------------------------------------------------------\n\n/**\n * Resolver for purpose/resource/subject. Can be a static string, a sync\n * function over Context, or an async function for cases where the resolver\n * needs to await `c.req.json()` (Hono request body is a stream until consumed).\n */\ntype StringOrFn = string | ((c: Context) => string) | ((c: Context) => Promise<string>);\n\n/**\n * Hono `Variables` shape expected on the context. Apps that consume this\n * middleware should type their Hono instance as:\n *\n * ```ts\n * const app = new Hono<{ Variables: BtxAdmissionVariables }>();\n * ```\n *\n * Then `c.get('btx')` is type-narrowed to `{ result: VerifyResult } | undefined`.\n */\nexport interface BtxAdmissionVariables {\n  btx: { result: VerifyResult };\n}\n\n/** Options for {@link btxAdmission}. */\nexport interface BtxAdmissionOpts {\n  /** The BTX RPC client (constructed once at boot). */\n  client: BtxChallengeClient;\n  /** Logical purpose label, e.g. `'ai_inference_gate'` or `'rate_limit'`. */\n  purpose: StringOrFn;\n  /** Resource identifier, e.g. `(c) => \\`model:${(await c.req.json()).model}|route:${c.req.path}\\``. */\n  resource: StringOrFn;\n  /** Subject identifier, e.g. `(c) => \\`tenant:${c.req.header('x-tenant-id')}\\``. */\n  subject: StringOrFn;\n  /** Extra issue params forwarded to `client.issue()` (target_solve_time_s, expires_in_s, etc.). */\n  issueParams?: Partial<Omit<IssueParams, 'purpose' | 'resource' | 'subject'>>;\n  /** Optional hook fired on successful admission. Receives `c` + the redeem result. */\n  onAdmit?: (c: Context, result: VerifyResult) => void;\n  /**\n   * Optional hook fired when `client.issue()` or `client.redeem()` throws.\n   * Receives the original error + the context. Fires exactly once before\n   * the middleware re-throws to hand off to Hono's `onError` handler.\n   * Use this for logging/observability. Audit ref: D-1.\n   */\n  onError?: (err: unknown, c: Context) => void;\n  /**\n   * Override the default \"is the proof present?\" check. By default it returns\n   * true iff all of `x-btx-challenge`, `x-btx-proof-nonce`, `x-btx-proof-digest`\n   * headers are set.\n   */\n  isProofPresent?: (c: Context) => boolean;\n}\n\n// ----------------------------------------------------------------------------\n// Middleware\n// ----------------------------------------------------------------------------\n\n/**\n * Build a Hono middleware that gates downstream handlers behind\n * a BTX service challenge. Use per-route by attaching it as a route argument.\n */\nexport function btxAdmission(opts: BtxAdmissionOpts): MiddlewareHandler {\n  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;\n\n  return async function btxAdmissionMiddleware(c, next) {\n    if (!proofPresent(c)) {\n      return issueAndRespond(c, opts);\n    }\n    return redeemAndAdmit(c, next, opts);\n  };\n}\n\nfunction defaultIsProofPresent(c: Context): boolean {\n  return Boolean(\n    c.req.header(HEADER_CHALLENGE) &&\n      c.req.header(HEADER_PROOF_NONCE) &&\n      c.req.header(HEADER_PROOF_DIGEST),\n  );\n}\n\nasync function issueAndRespond(c: Context, opts: BtxAdmissionOpts): Promise<Response> {\n  try {\n    const purpose = await resolve(opts.purpose, c);\n    const resource = await resolve(opts.resource, c);\n    const subject = await resolve(opts.subject, c);\n    const challenge = await opts.client.issue({\n      purpose,\n      resource,\n      subject,\n      ...opts.issueParams,\n    });\n    c.header(HEADER_CHALLENGE, JSON.stringify(challenge));\n    return c.json(\n      {\n        challenge,\n        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST],\n      },\n      402,\n    );\n  } catch (err) {\n    opts.onError?.(err, c);\n    throw err;\n  }\n}\n\nasync function redeemAndAdmit(\n  c: Context,\n  next: () => Promise<void>,\n  opts: BtxAdmissionOpts,\n): Promise<Response | void> {\n  const challengeRaw = c.req.header(HEADER_CHALLENGE);\n  const nonce = c.req.header(HEADER_PROOF_NONCE);\n  const digest = c.req.header(HEADER_PROOF_DIGEST);\n\n  if (!challengeRaw) {\n    return c.json(\n      {\n        error: 'missing_challenge_header',\n        message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`,\n      },\n      400,\n    );\n  }\n\n  let challenge: Challenge;\n  try {\n    challenge = JSON.parse(challengeRaw) as Challenge;\n  } catch {\n    return c.json(\n      {\n        error: 'malformed_challenge_header',\n        message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`,\n      },\n      400,\n    );\n  }\n\n  // Optional sanity check: if the client also sent the challenge_id header,\n  // make sure it matches the embedded id.\n  const idHeader = c.req.header(HEADER_CHALLENGE_ID);\n  if (idHeader && idHeader !== challenge.challenge_id) {\n    return c.json(\n      {\n        error: 'challenge_id_mismatch',\n        message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`,\n      },\n      400,\n    );\n  }\n\n  try {\n    const result = await opts.client.redeem(challenge, nonce!, digest!);\n    if (!result.valid) {\n      return c.json(\n        {\n          valid: false,\n          reason: result.reason,\n          expired: result.expired,\n        },\n        403,\n      );\n    }\n    c.set('btx', { result });\n    opts.onAdmit?.(c, result);\n    await next();\n    return;\n  } catch (err) {\n    opts.onError?.(err, c);\n    throw err;\n  }\n}\n\nasync function resolve(value: StringOrFn, c: Context): Promise<string> {\n  if (typeof value === 'function') {\n    return await value(c);\n  }\n  return value;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,114 @@
+import { Context, MiddlewareHandler } from 'hono';
+import { BtxChallengeClient, IssueParams, VerifyResult } from '@btx-tools/challenges-sdk';
+
+/**
+ * @btx-tools/middleware-hono
+ *
+ * Drop-in **Hono** admission gate backed by BTX service challenges.
+ * Mirrors the behavior of `@btx-tools/middleware-express` and
+ * `@btx-tools/middleware-fastify` for Hono's middleware model — works on
+ * Node, Deno, Bun, Cloudflare Workers, and other edge runtimes Hono targets.
+ *
+ * Flow (stateless, echo-the-challenge):
+ *
+ *   client → POST /v1/generate                          (no proof headers)
+ *   server →   402 Payment Required
+ *              X-BTX-Challenge: <stringified challenge JSON>
+ *              body: { challenge, retry_with: [...] }
+ *
+ *   client solves locally (or via RPC), retries:
+ *   client → POST /v1/generate
+ *              X-BTX-Challenge: <echoed challenge JSON>
+ *              X-BTX-Challenge-Id: <id>             (optional sanity check)
+ *              X-BTX-Proof-Nonce: <hex>
+ *              X-BTX-Proof-Digest: <hex>
+ *   server →   200 OK  (handler runs; c.get('btx').result is the VerifyResult)
+ *
+ *   Invalid proof → 403 with { valid: false, reason }.
+ *   btxd RPC error → throws — Hono's onError handler catches it.
+ *
+ * Usage (per-route):
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+ * import { btxAdmission } from '@btx-tools/middleware-hono';
+ *
+ * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });
+ * const app = new Hono<{ Variables: { btx: { result: import('@btx-tools/challenges-sdk').VerifyResult } } }>();
+ *
+ * app.post('/v1/generate',
+ *   btxAdmission({
+ *     client,
+ *     purpose: 'ai_inference_gate',
+ *     resource: (c) => `route:${c.req.path}`,
+ *     subject: async (c) => `tenant:${(await c.req.json()).tenant_id}`,
+ *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+ *   }),
+ *   async (c) => {
+ *     const admit = c.get('btx').result;
+ *     return c.json({ ok: true, reason: admit.reason });
+ *   },
+ * );
+ * ```
+ */
+
+declare const HEADER_CHALLENGE = "x-btx-challenge";
+declare const HEADER_CHALLENGE_ID = "x-btx-challenge-id";
+declare const HEADER_PROOF_NONCE = "x-btx-proof-nonce";
+declare const HEADER_PROOF_DIGEST = "x-btx-proof-digest";
+/**
+ * Resolver for purpose/resource/subject. Can be a static string, a sync
+ * function over Context, or an async function for cases where the resolver
+ * needs to await `c.req.json()` (Hono request body is a stream until consumed).
+ */
+type StringOrFn = string | ((c: Context) => string) | ((c: Context) => Promise<string>);
+/**
+ * Hono `Variables` shape expected on the context. Apps that consume this
+ * middleware should type their Hono instance as:
+ *
+ * ```ts
+ * const app = new Hono<{ Variables: BtxAdmissionVariables }>();
+ * ```
+ *
+ * Then `c.get('btx')` is type-narrowed to `{ result: VerifyResult } | undefined`.
+ */
+interface BtxAdmissionVariables {
+    btx: {
+        result: VerifyResult;
+    };
+}
+/** Options for {@link btxAdmission}. */
+interface BtxAdmissionOpts {
+    /** The BTX RPC client (constructed once at boot). */
+    client: BtxChallengeClient;
+    /** Logical purpose label, e.g. `'ai_inference_gate'` or `'rate_limit'`. */
+    purpose: StringOrFn;
+    /** Resource identifier, e.g. `(c) => \`model:${(await c.req.json()).model}|route:${c.req.path}\``. */
+    resource: StringOrFn;
+    /** Subject identifier, e.g. `(c) => \`tenant:${c.req.header('x-tenant-id')}\``. */
+    subject: StringOrFn;
+    /** Extra issue params forwarded to `client.issue()` (target_solve_time_s, expires_in_s, etc.). */
+    issueParams?: Partial<Omit<IssueParams, 'purpose' | 'resource' | 'subject'>>;
+    /** Optional hook fired on successful admission. Receives `c` + the redeem result. */
+    onAdmit?: (c: Context, result: VerifyResult) => void;
+    /**
+     * Optional hook fired when `client.issue()` or `client.redeem()` throws.
+     * Receives the original error + the context. Fires exactly once before
+     * the middleware re-throws to hand off to Hono's `onError` handler.
+     * Use this for logging/observability. Audit ref: D-1.
+     */
+    onError?: (err: unknown, c: Context) => void;
+    /**
+     * Override the default "is the proof present?" check. By default it returns
+     * true iff all of `x-btx-challenge`, `x-btx-proof-nonce`, `x-btx-proof-digest`
+     * headers are set.
+     */
+    isProofPresent?: (c: Context) => boolean;
+}
+/**
+ * Build a Hono middleware that gates downstream handlers behind
+ * a BTX service challenge. Use per-route by attaching it as a route argument.
+ */
+declare function btxAdmission(opts: BtxAdmissionOpts): MiddlewareHandler;
+
+export { type BtxAdmissionOpts, type BtxAdmissionVariables, HEADER_CHALLENGE, HEADER_CHALLENGE_ID, HEADER_PROOF_DIGEST, HEADER_PROOF_NONCE, btxAdmission };

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Context, MiddlewareHandler } from 'hono';
+import { BtxChallengeClient, IssueParams, VerifyResult } from '@btx-tools/challenges-sdk';
+
+/**
+ * @btx-tools/middleware-hono
+ *
+ * Drop-in **Hono** admission gate backed by BTX service challenges.
+ * Mirrors the behavior of `@btx-tools/middleware-express` and
+ * `@btx-tools/middleware-fastify` for Hono's middleware model — works on
+ * Node, Deno, Bun, Cloudflare Workers, and other edge runtimes Hono targets.
+ *
+ * Flow (stateless, echo-the-challenge):
+ *
+ *   client → POST /v1/generate                          (no proof headers)
+ *   server →   402 Payment Required
+ *              X-BTX-Challenge: <stringified challenge JSON>
+ *              body: { challenge, retry_with: [...] }
+ *
+ *   client solves locally (or via RPC), retries:
+ *   client → POST /v1/generate
+ *              X-BTX-Challenge: <echoed challenge JSON>
+ *              X-BTX-Challenge-Id: <id>             (optional sanity check)
+ *              X-BTX-Proof-Nonce: <hex>
+ *              X-BTX-Proof-Digest: <hex>
+ *   server →   200 OK  (handler runs; c.get('btx').result is the VerifyResult)
+ *
+ *   Invalid proof → 403 with { valid: false, reason }.
+ *   btxd RPC error → throws — Hono's onError handler catches it.
+ *
+ * Usage (per-route):
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+ * import { btxAdmission } from '@btx-tools/middleware-hono';
+ *
+ * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });
+ * const app = new Hono<{ Variables: { btx: { result: import('@btx-tools/challenges-sdk').VerifyResult } } }>();
+ *
+ * app.post('/v1/generate',
+ *   btxAdmission({
+ *     client,
+ *     purpose: 'ai_inference_gate',
+ *     resource: (c) => `route:${c.req.path}`,
+ *     subject: async (c) => `tenant:${(await c.req.json()).tenant_id}`,
+ *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+ *   }),
+ *   async (c) => {
+ *     const admit = c.get('btx').result;
+ *     return c.json({ ok: true, reason: admit.reason });
+ *   },
+ * );
+ * ```
+ */
+
+declare const HEADER_CHALLENGE = "x-btx-challenge";
+declare const HEADER_CHALLENGE_ID = "x-btx-challenge-id";
+declare const HEADER_PROOF_NONCE = "x-btx-proof-nonce";
+declare const HEADER_PROOF_DIGEST = "x-btx-proof-digest";
+/**
+ * Resolver for purpose/resource/subject. Can be a static string, a sync
+ * function over Context, or an async function for cases where the resolver
+ * needs to await `c.req.json()` (Hono request body is a stream until consumed).
+ */
+type StringOrFn = string | ((c: Context) => string) | ((c: Context) => Promise<string>);
+/**
+ * Hono `Variables` shape expected on the context. Apps that consume this
+ * middleware should type their Hono instance as:
+ *
+ * ```ts
+ * const app = new Hono<{ Variables: BtxAdmissionVariables }>();
+ * ```
+ *
+ * Then `c.get('btx')` is type-narrowed to `{ result: VerifyResult } | undefined`.
+ */
+interface BtxAdmissionVariables {
+    btx: {
+        result: VerifyResult;
+    };
+}
+/** Options for {@link btxAdmission}. */
+interface BtxAdmissionOpts {
+    /** The BTX RPC client (constructed once at boot). */
+    client: BtxChallengeClient;
+    /** Logical purpose label, e.g. `'ai_inference_gate'` or `'rate_limit'`. */
+    purpose: StringOrFn;
+    /** Resource identifier, e.g. `(c) => \`model:${(await c.req.json()).model}|route:${c.req.path}\``. */
+    resource: StringOrFn;
+    /** Subject identifier, e.g. `(c) => \`tenant:${c.req.header('x-tenant-id')}\``. */
+    subject: StringOrFn;
+    /** Extra issue params forwarded to `client.issue()` (target_solve_time_s, expires_in_s, etc.). */
+    issueParams?: Partial<Omit<IssueParams, 'purpose' | 'resource' | 'subject'>>;
+    /** Optional hook fired on successful admission. Receives `c` + the redeem result. */
+    onAdmit?: (c: Context, result: VerifyResult) => void;
+    /**
+     * Optional hook fired when `client.issue()` or `client.redeem()` throws.
+     * Receives the original error + the context. Fires exactly once before
+     * the middleware re-throws to hand off to Hono's `onError` handler.
+     * Use this for logging/observability. Audit ref: D-1.
+     */
+    onError?: (err: unknown, c: Context) => void;
+    /**
+     * Override the default "is the proof present?" check. By default it returns
+     * true iff all of `x-btx-challenge`, `x-btx-proof-nonce`, `x-btx-proof-digest`
+     * headers are set.
+     */
+    isProofPresent?: (c: Context) => boolean;
+}
+/**
+ * Build a Hono middleware that gates downstream handlers behind
+ * a BTX service challenge. Use per-route by attaching it as a route argument.
+ */
+declare function btxAdmission(opts: BtxAdmissionOpts): MiddlewareHandler;
+
+export { type BtxAdmissionOpts, type BtxAdmissionVariables, HEADER_CHALLENGE, HEADER_CHALLENGE_ID, HEADER_PROOF_DIGEST, HEADER_PROOF_NONCE, btxAdmission };

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/index.ts
+var HEADER_CHALLENGE = "x-btx-challenge";
+var HEADER_CHALLENGE_ID = "x-btx-challenge-id";
+var HEADER_PROOF_NONCE = "x-btx-proof-nonce";
+var HEADER_PROOF_DIGEST = "x-btx-proof-digest";
+function btxAdmission(opts) {
+  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;
+  return async function btxAdmissionMiddleware(c, next) {
+    if (!proofPresent(c)) {
+      return issueAndRespond(c, opts);
+    }
+    return redeemAndAdmit(c, next, opts);
+  };
+}
+function defaultIsProofPresent(c) {
+  return Boolean(
+    c.req.header(HEADER_CHALLENGE) && c.req.header(HEADER_PROOF_NONCE) && c.req.header(HEADER_PROOF_DIGEST)
+  );
+}
+async function issueAndRespond(c, opts) {
+  try {
+    const purpose = await resolve(opts.purpose, c);
+    const resource = await resolve(opts.resource, c);
+    const subject = await resolve(opts.subject, c);
+    const challenge = await opts.client.issue({
+      purpose,
+      resource,
+      subject,
+      ...opts.issueParams
+    });
+    c.header(HEADER_CHALLENGE, JSON.stringify(challenge));
+    return c.json(
+      {
+        challenge,
+        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST]
+      },
+      402
+    );
+  } catch (err) {
+    opts.onError?.(err, c);
+    throw err;
+  }
+}
+async function redeemAndAdmit(c, next, opts) {
+  const challengeRaw = c.req.header(HEADER_CHALLENGE);
+  const nonce = c.req.header(HEADER_PROOF_NONCE);
+  const digest = c.req.header(HEADER_PROOF_DIGEST);
+  if (!challengeRaw) {
+    return c.json(
+      {
+        error: "missing_challenge_header",
+        message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`
+      },
+      400
+    );
+  }
+  let challenge;
+  try {
+    challenge = JSON.parse(challengeRaw);
+  } catch {
+    return c.json(
+      {
+        error: "malformed_challenge_header",
+        message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`
+      },
+      400
+    );
+  }
+  const idHeader = c.req.header(HEADER_CHALLENGE_ID);
+  if (idHeader && idHeader !== challenge.challenge_id) {
+    return c.json(
+      {
+        error: "challenge_id_mismatch",
+        message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`
+      },
+      400
+    );
+  }
+  try {
+    const result = await opts.client.redeem(challenge, nonce, digest);
+    if (!result.valid) {
+      return c.json(
+        {
+          valid: false,
+          reason: result.reason,
+          expired: result.expired
+        },
+        403
+      );
+    }
+    c.set("btx", { result });
+    opts.onAdmit?.(c, result);
+    await next();
+    return;
+  } catch (err) {
+    opts.onError?.(err, c);
+    throw err;
+  }
+}
+async function resolve(value, c) {
+  if (typeof value === "function") {
+    return await value(c);
+  }
+  return value;
+}
+
+export { HEADER_CHALLENGE, HEADER_CHALLENGE_ID, HEADER_PROOF_DIGEST, HEADER_PROOF_NONCE, btxAdmission };
+//# 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 * @btx-tools/middleware-hono\n *\n * Drop-in **Hono** admission gate backed by BTX service challenges.\n * Mirrors the behavior of `@btx-tools/middleware-express` and\n * `@btx-tools/middleware-fastify` for Hono's middleware model — works on\n * Node, Deno, Bun, Cloudflare Workers, and other edge runtimes Hono targets.\n *\n * Flow (stateless, echo-the-challenge):\n *\n *   client → POST /v1/generate                          (no proof headers)\n *   server →   402 Payment Required\n *              X-BTX-Challenge: <stringified challenge JSON>\n *              body: { challenge, retry_with: [...] }\n *\n *   client solves locally (or via RPC), retries:\n *   client → POST /v1/generate\n *              X-BTX-Challenge: <echoed challenge JSON>\n *              X-BTX-Challenge-Id: <id>             (optional sanity check)\n *              X-BTX-Proof-Nonce: <hex>\n *              X-BTX-Proof-Digest: <hex>\n *   server →   200 OK  (handler runs; c.get('btx').result is the VerifyResult)\n *\n *   Invalid proof → 403 with { valid: false, reason }.\n *   btxd RPC error → throws — Hono's onError handler catches it.\n *\n * Usage (per-route):\n * ```ts\n * import { Hono } from 'hono';\n * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';\n * import { btxAdmission } from '@btx-tools/middleware-hono';\n *\n * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });\n * const app = new Hono<{ Variables: { btx: { result: import('@btx-tools/challenges-sdk').VerifyResult } } }>();\n *\n * app.post('/v1/generate',\n *   btxAdmission({\n *     client,\n *     purpose: 'ai_inference_gate',\n *     resource: (c) => `route:${c.req.path}`,\n *     subject: async (c) => `tenant:${(await c.req.json()).tenant_id}`,\n *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },\n *   }),\n *   async (c) => {\n *     const admit = c.get('btx').result;\n *     return c.json({ ok: true, reason: admit.reason });\n *   },\n * );\n * ```\n */\n\nimport type { Context, MiddlewareHandler } from 'hono';\n\nimport type {\n  BtxChallengeClient,\n  Challenge,\n  IssueParams,\n  VerifyResult,\n} from '@btx-tools/challenges-sdk';\n\n// ----------------------------------------------------------------------------\n// Public constants\n// ----------------------------------------------------------------------------\n\nexport const HEADER_CHALLENGE = 'x-btx-challenge';\nexport const HEADER_CHALLENGE_ID = 'x-btx-challenge-id';\nexport const HEADER_PROOF_NONCE = 'x-btx-proof-nonce';\nexport const HEADER_PROOF_DIGEST = 'x-btx-proof-digest';\n// Note: Web standard Headers (which Hono uses) are case-insensitive on get but\n// typically lowercased internally. Use lowercase names to keep consistent.\n\n// ----------------------------------------------------------------------------\n// Types\n// ----------------------------------------------------------------------------\n\n/**\n * Resolver for purpose/resource/subject. Can be a static string, a sync\n * function over Context, or an async function for cases where the resolver\n * needs to await `c.req.json()` (Hono request body is a stream until consumed).\n */\ntype StringOrFn = string | ((c: Context) => string) | ((c: Context) => Promise<string>);\n\n/**\n * Hono `Variables` shape expected on the context. Apps that consume this\n * middleware should type their Hono instance as:\n *\n * ```ts\n * const app = new Hono<{ Variables: BtxAdmissionVariables }>();\n * ```\n *\n * Then `c.get('btx')` is type-narrowed to `{ result: VerifyResult } | undefined`.\n */\nexport interface BtxAdmissionVariables {\n  btx: { result: VerifyResult };\n}\n\n/** Options for {@link btxAdmission}. */\nexport interface BtxAdmissionOpts {\n  /** The BTX RPC client (constructed once at boot). */\n  client: BtxChallengeClient;\n  /** Logical purpose label, e.g. `'ai_inference_gate'` or `'rate_limit'`. */\n  purpose: StringOrFn;\n  /** Resource identifier, e.g. `(c) => \\`model:${(await c.req.json()).model}|route:${c.req.path}\\``. */\n  resource: StringOrFn;\n  /** Subject identifier, e.g. `(c) => \\`tenant:${c.req.header('x-tenant-id')}\\``. */\n  subject: StringOrFn;\n  /** Extra issue params forwarded to `client.issue()` (target_solve_time_s, expires_in_s, etc.). */\n  issueParams?: Partial<Omit<IssueParams, 'purpose' | 'resource' | 'subject'>>;\n  /** Optional hook fired on successful admission. Receives `c` + the redeem result. */\n  onAdmit?: (c: Context, result: VerifyResult) => void;\n  /**\n   * Optional hook fired when `client.issue()` or `client.redeem()` throws.\n   * Receives the original error + the context. Fires exactly once before\n   * the middleware re-throws to hand off to Hono's `onError` handler.\n   * Use this for logging/observability. Audit ref: D-1.\n   */\n  onError?: (err: unknown, c: Context) => void;\n  /**\n   * Override the default \"is the proof present?\" check. By default it returns\n   * true iff all of `x-btx-challenge`, `x-btx-proof-nonce`, `x-btx-proof-digest`\n   * headers are set.\n   */\n  isProofPresent?: (c: Context) => boolean;\n}\n\n// ----------------------------------------------------------------------------\n// Middleware\n// ----------------------------------------------------------------------------\n\n/**\n * Build a Hono middleware that gates downstream handlers behind\n * a BTX service challenge. Use per-route by attaching it as a route argument.\n */\nexport function btxAdmission(opts: BtxAdmissionOpts): MiddlewareHandler {\n  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;\n\n  return async function btxAdmissionMiddleware(c, next) {\n    if (!proofPresent(c)) {\n      return issueAndRespond(c, opts);\n    }\n    return redeemAndAdmit(c, next, opts);\n  };\n}\n\nfunction defaultIsProofPresent(c: Context): boolean {\n  return Boolean(\n    c.req.header(HEADER_CHALLENGE) &&\n      c.req.header(HEADER_PROOF_NONCE) &&\n      c.req.header(HEADER_PROOF_DIGEST),\n  );\n}\n\nasync function issueAndRespond(c: Context, opts: BtxAdmissionOpts): Promise<Response> {\n  try {\n    const purpose = await resolve(opts.purpose, c);\n    const resource = await resolve(opts.resource, c);\n    const subject = await resolve(opts.subject, c);\n    const challenge = await opts.client.issue({\n      purpose,\n      resource,\n      subject,\n      ...opts.issueParams,\n    });\n    c.header(HEADER_CHALLENGE, JSON.stringify(challenge));\n    return c.json(\n      {\n        challenge,\n        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST],\n      },\n      402,\n    );\n  } catch (err) {\n    opts.onError?.(err, c);\n    throw err;\n  }\n}\n\nasync function redeemAndAdmit(\n  c: Context,\n  next: () => Promise<void>,\n  opts: BtxAdmissionOpts,\n): Promise<Response | void> {\n  const challengeRaw = c.req.header(HEADER_CHALLENGE);\n  const nonce = c.req.header(HEADER_PROOF_NONCE);\n  const digest = c.req.header(HEADER_PROOF_DIGEST);\n\n  if (!challengeRaw) {\n    return c.json(\n      {\n        error: 'missing_challenge_header',\n        message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`,\n      },\n      400,\n    );\n  }\n\n  let challenge: Challenge;\n  try {\n    challenge = JSON.parse(challengeRaw) as Challenge;\n  } catch {\n    return c.json(\n      {\n        error: 'malformed_challenge_header',\n        message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`,\n      },\n      400,\n    );\n  }\n\n  // Optional sanity check: if the client also sent the challenge_id header,\n  // make sure it matches the embedded id.\n  const idHeader = c.req.header(HEADER_CHALLENGE_ID);\n  if (idHeader && idHeader !== challenge.challenge_id) {\n    return c.json(\n      {\n        error: 'challenge_id_mismatch',\n        message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`,\n      },\n      400,\n    );\n  }\n\n  try {\n    const result = await opts.client.redeem(challenge, nonce!, digest!);\n    if (!result.valid) {\n      return c.json(\n        {\n          valid: false,\n          reason: result.reason,\n          expired: result.expired,\n        },\n        403,\n      );\n    }\n    c.set('btx', { result });\n    opts.onAdmit?.(c, result);\n    await next();\n    return;\n  } catch (err) {\n    opts.onError?.(err, c);\n    throw err;\n  }\n}\n\nasync function resolve(value: StringOrFn, c: Context): Promise<string> {\n  if (typeof value === 'function') {\n    return await value(c);\n  }\n  return value;\n}\n"]}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@btx-tools/middleware-hono",
+  "version": "0.1.0",
+  "description": "Hono middleware for @btx-tools/challenges-sdk — drop-in BTX service-challenge admission gate (Node + edge)",
+  "author": "visitor-code <visitor@friction.market>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@btx-tools/challenges-sdk": "^0.0.4 || ^0.1.0",
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "hono": "^4.6.0",
+    "prettier": "^3.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "@btx-tools/challenges-sdk": "0.1.0"
+  },
+  "keywords": [
+    "btx",
+    "hono",
+    "middleware",
+    "edge",
+    "cloudflare-workers",
+    "deno",
+    "admission",
+    "rate-limit",
+    "captcha",
+    "ai-gating",
+    "service-challenges",
+    "proof-of-work"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/btx-tools/btx-challenges-sdk.git",
+    "directory": "packages/middleware-hono"
+  },
+  "homepage": "https://github.com/btx-tools/btx-challenges-sdk/tree/main/packages/middleware-hono#readme",
+  "bugs": {
+    "url": "https://github.com/btx-tools/btx-challenges-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+  }
+}