@btx-tools/middleware-fastify 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,96 @@
+# @btx-tools/middleware-fastify
+
+Drop-in **Fastify** admission gate backed by BTX service challenges. Same flow + ergonomics as [`@btx-tools/middleware-express`](https://www.npmjs.com/package/@btx-tools/middleware-express), tailored to Fastify's preHandler hook + reply API.
+
+```bash
+pnpm add @btx-tools/middleware-fastify @btx-tools/challenges-sdk fastify
+```
+
+## Quickstart
+
+```ts
+import Fastify from 'fastify';
+import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+import { btxAdmission } from '@btx-tools/middleware-fastify';
+
+const client = new BtxChallengeClient({
+  rpcUrl: 'http://127.0.0.1:19334',
+  rpcAuth: { user: 'rpcuser', pass: 'rpcpass' },
+});
+
+const fastify = Fastify();
+
+fastify.post('/v1/generate', {
+  preHandler: btxAdmission({
+    client,
+    purpose: 'ai_inference_gate',
+    resource: (req) => `model:${(req.body as any).model}|route:${req.url}`,
+    subject: (req) => `tenant:${(req.body as any).tenant_id}`,
+    issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+    onError: (err, req) => req.log.error({ err }, 'btx admission error'),
+  }),
+}, async (request, reply) => {
+  // request.btx?.result is populated with the redeem VerifyResult
+  return { ok: true, generated: '...' };
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+## 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 `request.btx = { result }` and runs the route handler. Else replies `403`.
+
+No server-side challenge store; the client echoes the challenge back. Scales horizontally. Cons: the challenge JSON (~3-5 KB) lives in an HTTP header, so check your reverse proxy's `large_client_header_buffers` / equivalent.
+
+## API
+
+### `btxAdmission(opts): preHandlerAsyncHookHandler`
+
+Returns a Fastify preHandler hook to attach per-route.
+
+#### Options
+
+| Field | Type | Notes |
+|---|---|---|
+| `client` | `BtxChallengeClient` | required. Construct once at boot. |
+| `purpose` | `string \| (req) => string` | required. Logical purpose label. |
+| `resource` | `string \| (req) => string` | required. Resource identifier. |
+| `subject` | `string \| (req) => string` | required. Subject identifier. |
+| `issueParams` | `Partial<IssueParams>` | optional. Extra params forwarded to `client.issue()`. |
+| `onAdmit` | `(req, result) => void` | optional. Fires on successful admission. |
+| `onError` | `(err, req) => void` | optional. Fires when `client.issue()` or `client.redeem()` throws, exactly once before the preHandler re-throws. Use for logging. Audit ref: D-1. |
+| `isProofPresent` | `(req) => boolean` | optional. Override the default `headers[x-btx-challenge] && headers[x-btx-proof-nonce] && headers[x-btx-proof-digest]` check. |
+
+### 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'` |
+
+(Fastify lowercases incoming header names, hence the lowercase form here. Outgoing `reply.header()` accepts any case.)
+
+## Error handling
+
+When `client.issue()` or `client.redeem()` throws (e.g., btxd RPC down, network error), the middleware:
+1. Calls `opts.onError(err, req)` if provided
+2. Re-throws — Fastify's standard error-handling pipeline kicks in (default 500, or whatever your error handler returns)
+
+For HTTPS / production deployments, terminate TLS at a reverse proxy (Caddy, nginx, Cloudflare) in front of btxd. **Do NOT expose btxd's RPC port directly to the public internet.**
+
+## Requirements
+
+- **Node.js** ≥ 18.17
+- **Fastify** ^4.0.0 or ^5.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,103 @@
+'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 btxAdmissionPreHandler(request, reply) {
+    if (!proofPresent(request)) {
+      await issueAndRespond(request, reply, opts);
+      return;
+    }
+    await redeemAndAdmit(request, reply, opts);
+  };
+}
+function defaultIsProofPresent(req) {
+  const h = req.headers;
+  return Boolean(h[HEADER_CHALLENGE] && h[HEADER_PROOF_NONCE] && h[HEADER_PROOF_DIGEST]);
+}
+async function issueAndRespond(req, reply, opts) {
+  try {
+    const purpose = resolve(opts.purpose, req);
+    const resource = resolve(opts.resource, req);
+    const subject = resolve(opts.subject, req);
+    const challenge = await opts.client.issue({
+      purpose,
+      resource,
+      subject,
+      ...opts.issueParams
+    });
+    await reply.code(402).header(HEADER_CHALLENGE, JSON.stringify(challenge)).header("content-type", "application/json").send({
+      challenge,
+      retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST]
+    });
+  } catch (err) {
+    opts.onError?.(err, req);
+    throw err;
+  }
+}
+async function redeemAndAdmit(req, reply, opts) {
+  const challengeRaw = headerValue(req, HEADER_CHALLENGE);
+  const nonce = headerValue(req, HEADER_PROOF_NONCE);
+  const digest = headerValue(req, HEADER_PROOF_DIGEST);
+  if (!challengeRaw) {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "missing_challenge_header",
+      message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`
+    });
+    return;
+  }
+  let challenge;
+  try {
+    challenge = JSON.parse(challengeRaw);
+  } catch {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "malformed_challenge_header",
+      message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`
+    });
+    return;
+  }
+  const idHeader = headerValue(req, HEADER_CHALLENGE_ID);
+  if (idHeader && idHeader !== challenge.challenge_id) {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "challenge_id_mismatch",
+      message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`
+    });
+    return;
+  }
+  try {
+    const result = await opts.client.redeem(challenge, nonce, digest);
+    if (!result.valid) {
+      await reply.code(403).header("content-type", "application/json").send({
+        valid: false,
+        reason: result.reason,
+        expired: result.expired
+      });
+      return;
+    }
+    req.btx = { result };
+    opts.onAdmit?.(req, result);
+  } catch (err) {
+    opts.onError?.(err, req);
+    throw err;
+  }
+}
+function resolve(value, req) {
+  return typeof value === "function" ? value(req) : value;
+}
+function headerValue(req, name) {
+  const v = req.headers[name];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+
+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-fastify\n *\n * Drop-in Fastify admission gate backed by BTX service challenges.\n * Mirrors the behavior of `@btx-tools/middleware-express` for the Fastify\n * ecosystem.\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; request.btx?.result is the VerifyResult)\n *\n *   Invalid proof → 403 with { valid: false, reason }.\n *   btxd RPC error → Fastify's error pipeline (throw from preHandler).\n *\n * Stateless design notes:\n *  - Server never stores issued challenges; client echoes the challenge back\n *    in `X-BTX-Challenge`. Pros: scales horizontally, no sticky routing.\n *    Cons: the challenge JSON (~3-5 KB) lives in an HTTP header, so check\n *    your reverse proxy's `large_client_header_buffers` / equivalent.\n *  - A stateful variant (server-side `challenge_id` cache) is a future\n *    enhancement queued as `btxAdmission({ store })`.\n *\n * Usage (per-route):\n * ```ts\n * import Fastify from 'fastify';\n * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';\n * import { btxAdmission } from '@btx-tools/middleware-fastify';\n *\n * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });\n * const fastify = Fastify();\n *\n * fastify.post('/v1/generate', {\n *   preHandler: btxAdmission({\n *     client,\n *     purpose: 'ai_inference_gate',\n *     resource: (req) => `model:${(req.body as any).model}|route:${req.url}`,\n *     subject: (req) => `tenant:${(req.body as any).tenant_id}`,\n *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },\n *   }),\n * }, async (request, reply) => {\n *   // request.btx?.result is populated with the redeem VerifyResult\n *   return { ok: true };\n * });\n * ```\n */\n\nimport type {\n  FastifyReply,\n  FastifyRequest,\n  preHandlerAsyncHookHandler,\n} from 'fastify';\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: Fastify normalizes incoming header names to lowercase. Outgoing\n// reply.header() accepts any case.\n\n// ----------------------------------------------------------------------------\n// Types\n// ----------------------------------------------------------------------------\n\ntype StringOrFn = string | ((req: FastifyRequest) => string);\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. `(req) => \\`model:${req.body.model}|route:${req.url}\\``. */\n  resource: StringOrFn;\n  /** Subject identifier, e.g. `(req) => \\`tenant:${req.user.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 `req` + the redeem result. */\n  onAdmit?: (req: FastifyRequest, result: VerifyResult) => void;\n  /**\n   * Optional hook fired when `client.issue()` or `client.redeem()` throws.\n   * Receives the original error + the request. Fires exactly once before\n   * the preHandler re-throws to hand off to Fastify's error pipeline.\n   * Use this for logging/observability — don't mutate the error or the\n   * reply. Audit ref: D-1.\n   */\n  onError?: (err: unknown, req: FastifyRequest) => 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   * are set.\n   */\n  isProofPresent?: (req: FastifyRequest) => boolean;\n}\n\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    /**\n     * Namespaced container for BTX middleware state. Populated on successful\n     * admission. Mirrors `req.btx` from middleware-express (audit C-3 namespace).\n     */\n    btx?: {\n      /** The `client.redeem()` result that admitted this request. */\n      result: VerifyResult;\n    };\n  }\n}\n\n// ----------------------------------------------------------------------------\n// Middleware\n// ----------------------------------------------------------------------------\n\n/**\n * Build a Fastify `preHandler` hook that gates downstream handlers behind\n * a BTX service challenge. Use per-route via `{ preHandler: btxAdmission(opts) }`.\n */\nexport function btxAdmission(opts: BtxAdmissionOpts): preHandlerAsyncHookHandler {\n  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;\n\n  return async function btxAdmissionPreHandler(request, reply) {\n    if (!proofPresent(request)) {\n      await issueAndRespond(request, reply, opts);\n      return;\n    }\n    await redeemAndAdmit(request, reply, opts);\n  };\n}\n\nfunction defaultIsProofPresent(req: FastifyRequest): boolean {\n  const h = req.headers;\n  return Boolean(h[HEADER_CHALLENGE] && h[HEADER_PROOF_NONCE] && h[HEADER_PROOF_DIGEST]);\n}\n\nasync function issueAndRespond(\n  req: FastifyRequest,\n  reply: FastifyReply,\n  opts: BtxAdmissionOpts,\n): Promise<void> {\n  try {\n    const purpose = resolve(opts.purpose, req);\n    const resource = resolve(opts.resource, req);\n    const subject = resolve(opts.subject, req);\n    const challenge = await opts.client.issue({\n      purpose,\n      resource,\n      subject,\n      ...opts.issueParams,\n    });\n    await reply\n      .code(402)\n      .header(HEADER_CHALLENGE, JSON.stringify(challenge))\n      .header('content-type', 'application/json')\n      .send({\n        challenge,\n        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST],\n      });\n  } catch (err) {\n    opts.onError?.(err, req);\n    throw err;\n  }\n}\n\nasync function redeemAndAdmit(\n  req: FastifyRequest,\n  reply: FastifyReply,\n  opts: BtxAdmissionOpts,\n): Promise<void> {\n  const challengeRaw = headerValue(req, HEADER_CHALLENGE);\n  const nonce = headerValue(req, HEADER_PROOF_NONCE);\n  const digest = headerValue(req, HEADER_PROOF_DIGEST);\n\n  if (!challengeRaw) {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'missing_challenge_header',\n      message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`,\n    });\n    return;\n  }\n\n  let challenge: Challenge;\n  try {\n    challenge = JSON.parse(challengeRaw) as Challenge;\n  } catch {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'malformed_challenge_header',\n      message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`,\n    });\n    return;\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 = headerValue(req, HEADER_CHALLENGE_ID);\n  if (idHeader && idHeader !== challenge.challenge_id) {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'challenge_id_mismatch',\n      message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`,\n    });\n    return;\n  }\n\n  try {\n    const result = await opts.client.redeem(challenge, nonce!, digest!);\n    if (!result.valid) {\n      await reply.code(403).header('content-type', 'application/json').send({\n        valid: false,\n        reason: result.reason,\n        expired: result.expired,\n      });\n      return;\n    }\n    req.btx = { result };\n    opts.onAdmit?.(req, result);\n    // Fall through to the route handler — no explicit reply.send here.\n  } catch (err) {\n    opts.onError?.(err, req);\n    throw err;\n  }\n}\n\nfunction resolve(value: StringOrFn, req: FastifyRequest): string {\n  return typeof value === 'function' ? value(req) : value;\n}\n\n/** Fastify header values can be string | string[] | undefined; normalize to string. */\nfunction headerValue(req: FastifyRequest, name: string): string | undefined {\n  const v = req.headers[name];\n  if (Array.isArray(v)) return v[0];\n  return v;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import { FastifyRequest, preHandlerAsyncHookHandler } from 'fastify';
+import { VerifyResult, BtxChallengeClient, IssueParams } from '@btx-tools/challenges-sdk';
+
+/**
+ * @btx-tools/middleware-fastify
+ *
+ * Drop-in Fastify admission gate backed by BTX service challenges.
+ * Mirrors the behavior of `@btx-tools/middleware-express` for the Fastify
+ * ecosystem.
+ *
+ * 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; request.btx?.result is the VerifyResult)
+ *
+ *   Invalid proof → 403 with { valid: false, reason }.
+ *   btxd RPC error → Fastify's error pipeline (throw from preHandler).
+ *
+ * Stateless design notes:
+ *  - Server never stores issued challenges; client echoes the challenge back
+ *    in `X-BTX-Challenge`. Pros: scales horizontally, no sticky routing.
+ *    Cons: the challenge JSON (~3-5 KB) lives in an HTTP header, so check
+ *    your reverse proxy's `large_client_header_buffers` / equivalent.
+ *  - A stateful variant (server-side `challenge_id` cache) is a future
+ *    enhancement queued as `btxAdmission({ store })`.
+ *
+ * Usage (per-route):
+ * ```ts
+ * import Fastify from 'fastify';
+ * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+ * import { btxAdmission } from '@btx-tools/middleware-fastify';
+ *
+ * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });
+ * const fastify = Fastify();
+ *
+ * fastify.post('/v1/generate', {
+ *   preHandler: btxAdmission({
+ *     client,
+ *     purpose: 'ai_inference_gate',
+ *     resource: (req) => `model:${(req.body as any).model}|route:${req.url}`,
+ *     subject: (req) => `tenant:${(req.body as any).tenant_id}`,
+ *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+ *   }),
+ * }, async (request, reply) => {
+ *   // request.btx?.result is populated with the redeem VerifyResult
+ *   return { ok: true };
+ * });
+ * ```
+ */
+
+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";
+type StringOrFn = string | ((req: FastifyRequest) => string);
+/** 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. `(req) => \`model:${req.body.model}|route:${req.url}\``. */
+    resource: StringOrFn;
+    /** Subject identifier, e.g. `(req) => \`tenant:${req.user.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 `req` + the redeem result. */
+    onAdmit?: (req: FastifyRequest, result: VerifyResult) => void;
+    /**
+     * Optional hook fired when `client.issue()` or `client.redeem()` throws.
+     * Receives the original error + the request. Fires exactly once before
+     * the preHandler re-throws to hand off to Fastify's error pipeline.
+     * Use this for logging/observability — don't mutate the error or the
+     * reply. Audit ref: D-1.
+     */
+    onError?: (err: unknown, req: FastifyRequest) => 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`
+     * are set.
+     */
+    isProofPresent?: (req: FastifyRequest) => boolean;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /**
+         * Namespaced container for BTX middleware state. Populated on successful
+         * admission. Mirrors `req.btx` from middleware-express (audit C-3 namespace).
+         */
+        btx?: {
+            /** The `client.redeem()` result that admitted this request. */
+            result: VerifyResult;
+        };
+    }
+}
+/**
+ * Build a Fastify `preHandler` hook that gates downstream handlers behind
+ * a BTX service challenge. Use per-route via `{ preHandler: btxAdmission(opts) }`.
+ */
+declare function btxAdmission(opts: BtxAdmissionOpts): preHandlerAsyncHookHandler;
+
+export { type BtxAdmissionOpts, HEADER_CHALLENGE, HEADER_CHALLENGE_ID, HEADER_PROOF_DIGEST, HEADER_PROOF_NONCE, btxAdmission };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { FastifyRequest, preHandlerAsyncHookHandler } from 'fastify';
+import { VerifyResult, BtxChallengeClient, IssueParams } from '@btx-tools/challenges-sdk';
+
+/**
+ * @btx-tools/middleware-fastify
+ *
+ * Drop-in Fastify admission gate backed by BTX service challenges.
+ * Mirrors the behavior of `@btx-tools/middleware-express` for the Fastify
+ * ecosystem.
+ *
+ * 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; request.btx?.result is the VerifyResult)
+ *
+ *   Invalid proof → 403 with { valid: false, reason }.
+ *   btxd RPC error → Fastify's error pipeline (throw from preHandler).
+ *
+ * Stateless design notes:
+ *  - Server never stores issued challenges; client echoes the challenge back
+ *    in `X-BTX-Challenge`. Pros: scales horizontally, no sticky routing.
+ *    Cons: the challenge JSON (~3-5 KB) lives in an HTTP header, so check
+ *    your reverse proxy's `large_client_header_buffers` / equivalent.
+ *  - A stateful variant (server-side `challenge_id` cache) is a future
+ *    enhancement queued as `btxAdmission({ store })`.
+ *
+ * Usage (per-route):
+ * ```ts
+ * import Fastify from 'fastify';
+ * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';
+ * import { btxAdmission } from '@btx-tools/middleware-fastify';
+ *
+ * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });
+ * const fastify = Fastify();
+ *
+ * fastify.post('/v1/generate', {
+ *   preHandler: btxAdmission({
+ *     client,
+ *     purpose: 'ai_inference_gate',
+ *     resource: (req) => `model:${(req.body as any).model}|route:${req.url}`,
+ *     subject: (req) => `tenant:${(req.body as any).tenant_id}`,
+ *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },
+ *   }),
+ * }, async (request, reply) => {
+ *   // request.btx?.result is populated with the redeem VerifyResult
+ *   return { ok: true };
+ * });
+ * ```
+ */
+
+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";
+type StringOrFn = string | ((req: FastifyRequest) => string);
+/** 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. `(req) => \`model:${req.body.model}|route:${req.url}\``. */
+    resource: StringOrFn;
+    /** Subject identifier, e.g. `(req) => \`tenant:${req.user.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 `req` + the redeem result. */
+    onAdmit?: (req: FastifyRequest, result: VerifyResult) => void;
+    /**
+     * Optional hook fired when `client.issue()` or `client.redeem()` throws.
+     * Receives the original error + the request. Fires exactly once before
+     * the preHandler re-throws to hand off to Fastify's error pipeline.
+     * Use this for logging/observability — don't mutate the error or the
+     * reply. Audit ref: D-1.
+     */
+    onError?: (err: unknown, req: FastifyRequest) => 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`
+     * are set.
+     */
+    isProofPresent?: (req: FastifyRequest) => boolean;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /**
+         * Namespaced container for BTX middleware state. Populated on successful
+         * admission. Mirrors `req.btx` from middleware-express (audit C-3 namespace).
+         */
+        btx?: {
+            /** The `client.redeem()` result that admitted this request. */
+            result: VerifyResult;
+        };
+    }
+}
+/**
+ * Build a Fastify `preHandler` hook that gates downstream handlers behind
+ * a BTX service challenge. Use per-route via `{ preHandler: btxAdmission(opts) }`.
+ */
+declare function btxAdmission(opts: BtxAdmissionOpts): preHandlerAsyncHookHandler;
+
+export { type BtxAdmissionOpts, HEADER_CHALLENGE, HEADER_CHALLENGE_ID, HEADER_PROOF_DIGEST, HEADER_PROOF_NONCE, btxAdmission };

package/dist/index.js

@@ -0,0 +1,97 @@
+// 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 btxAdmissionPreHandler(request, reply) {
+    if (!proofPresent(request)) {
+      await issueAndRespond(request, reply, opts);
+      return;
+    }
+    await redeemAndAdmit(request, reply, opts);
+  };
+}
+function defaultIsProofPresent(req) {
+  const h = req.headers;
+  return Boolean(h[HEADER_CHALLENGE] && h[HEADER_PROOF_NONCE] && h[HEADER_PROOF_DIGEST]);
+}
+async function issueAndRespond(req, reply, opts) {
+  try {
+    const purpose = resolve(opts.purpose, req);
+    const resource = resolve(opts.resource, req);
+    const subject = resolve(opts.subject, req);
+    const challenge = await opts.client.issue({
+      purpose,
+      resource,
+      subject,
+      ...opts.issueParams
+    });
+    await reply.code(402).header(HEADER_CHALLENGE, JSON.stringify(challenge)).header("content-type", "application/json").send({
+      challenge,
+      retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST]
+    });
+  } catch (err) {
+    opts.onError?.(err, req);
+    throw err;
+  }
+}
+async function redeemAndAdmit(req, reply, opts) {
+  const challengeRaw = headerValue(req, HEADER_CHALLENGE);
+  const nonce = headerValue(req, HEADER_PROOF_NONCE);
+  const digest = headerValue(req, HEADER_PROOF_DIGEST);
+  if (!challengeRaw) {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "missing_challenge_header",
+      message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`
+    });
+    return;
+  }
+  let challenge;
+  try {
+    challenge = JSON.parse(challengeRaw);
+  } catch {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "malformed_challenge_header",
+      message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`
+    });
+    return;
+  }
+  const idHeader = headerValue(req, HEADER_CHALLENGE_ID);
+  if (idHeader && idHeader !== challenge.challenge_id) {
+    await reply.code(400).header("content-type", "application/json").send({
+      error: "challenge_id_mismatch",
+      message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`
+    });
+    return;
+  }
+  try {
+    const result = await opts.client.redeem(challenge, nonce, digest);
+    if (!result.valid) {
+      await reply.code(403).header("content-type", "application/json").send({
+        valid: false,
+        reason: result.reason,
+        expired: result.expired
+      });
+      return;
+    }
+    req.btx = { result };
+    opts.onAdmit?.(req, result);
+  } catch (err) {
+    opts.onError?.(err, req);
+    throw err;
+  }
+}
+function resolve(value, req) {
+  return typeof value === "function" ? value(req) : value;
+}
+function headerValue(req, name) {
+  const v = req.headers[name];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+
+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-fastify\n *\n * Drop-in Fastify admission gate backed by BTX service challenges.\n * Mirrors the behavior of `@btx-tools/middleware-express` for the Fastify\n * ecosystem.\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; request.btx?.result is the VerifyResult)\n *\n *   Invalid proof → 403 with { valid: false, reason }.\n *   btxd RPC error → Fastify's error pipeline (throw from preHandler).\n *\n * Stateless design notes:\n *  - Server never stores issued challenges; client echoes the challenge back\n *    in `X-BTX-Challenge`. Pros: scales horizontally, no sticky routing.\n *    Cons: the challenge JSON (~3-5 KB) lives in an HTTP header, so check\n *    your reverse proxy's `large_client_header_buffers` / equivalent.\n *  - A stateful variant (server-side `challenge_id` cache) is a future\n *    enhancement queued as `btxAdmission({ store })`.\n *\n * Usage (per-route):\n * ```ts\n * import Fastify from 'fastify';\n * import { BtxChallengeClient } from '@btx-tools/challenges-sdk';\n * import { btxAdmission } from '@btx-tools/middleware-fastify';\n *\n * const client = new BtxChallengeClient({ rpcUrl: '...', rpcAuth: { user, pass } });\n * const fastify = Fastify();\n *\n * fastify.post('/v1/generate', {\n *   preHandler: btxAdmission({\n *     client,\n *     purpose: 'ai_inference_gate',\n *     resource: (req) => `model:${(req.body as any).model}|route:${req.url}`,\n *     subject: (req) => `tenant:${(req.body as any).tenant_id}`,\n *     issueParams: { target_solve_time_s: 1.0, expires_in_s: 60 },\n *   }),\n * }, async (request, reply) => {\n *   // request.btx?.result is populated with the redeem VerifyResult\n *   return { ok: true };\n * });\n * ```\n */\n\nimport type {\n  FastifyReply,\n  FastifyRequest,\n  preHandlerAsyncHookHandler,\n} from 'fastify';\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: Fastify normalizes incoming header names to lowercase. Outgoing\n// reply.header() accepts any case.\n\n// ----------------------------------------------------------------------------\n// Types\n// ----------------------------------------------------------------------------\n\ntype StringOrFn = string | ((req: FastifyRequest) => string);\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. `(req) => \\`model:${req.body.model}|route:${req.url}\\``. */\n  resource: StringOrFn;\n  /** Subject identifier, e.g. `(req) => \\`tenant:${req.user.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 `req` + the redeem result. */\n  onAdmit?: (req: FastifyRequest, result: VerifyResult) => void;\n  /**\n   * Optional hook fired when `client.issue()` or `client.redeem()` throws.\n   * Receives the original error + the request. Fires exactly once before\n   * the preHandler re-throws to hand off to Fastify's error pipeline.\n   * Use this for logging/observability — don't mutate the error or the\n   * reply. Audit ref: D-1.\n   */\n  onError?: (err: unknown, req: FastifyRequest) => 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   * are set.\n   */\n  isProofPresent?: (req: FastifyRequest) => boolean;\n}\n\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    /**\n     * Namespaced container for BTX middleware state. Populated on successful\n     * admission. Mirrors `req.btx` from middleware-express (audit C-3 namespace).\n     */\n    btx?: {\n      /** The `client.redeem()` result that admitted this request. */\n      result: VerifyResult;\n    };\n  }\n}\n\n// ----------------------------------------------------------------------------\n// Middleware\n// ----------------------------------------------------------------------------\n\n/**\n * Build a Fastify `preHandler` hook that gates downstream handlers behind\n * a BTX service challenge. Use per-route via `{ preHandler: btxAdmission(opts) }`.\n */\nexport function btxAdmission(opts: BtxAdmissionOpts): preHandlerAsyncHookHandler {\n  const proofPresent = opts.isProofPresent ?? defaultIsProofPresent;\n\n  return async function btxAdmissionPreHandler(request, reply) {\n    if (!proofPresent(request)) {\n      await issueAndRespond(request, reply, opts);\n      return;\n    }\n    await redeemAndAdmit(request, reply, opts);\n  };\n}\n\nfunction defaultIsProofPresent(req: FastifyRequest): boolean {\n  const h = req.headers;\n  return Boolean(h[HEADER_CHALLENGE] && h[HEADER_PROOF_NONCE] && h[HEADER_PROOF_DIGEST]);\n}\n\nasync function issueAndRespond(\n  req: FastifyRequest,\n  reply: FastifyReply,\n  opts: BtxAdmissionOpts,\n): Promise<void> {\n  try {\n    const purpose = resolve(opts.purpose, req);\n    const resource = resolve(opts.resource, req);\n    const subject = resolve(opts.subject, req);\n    const challenge = await opts.client.issue({\n      purpose,\n      resource,\n      subject,\n      ...opts.issueParams,\n    });\n    await reply\n      .code(402)\n      .header(HEADER_CHALLENGE, JSON.stringify(challenge))\n      .header('content-type', 'application/json')\n      .send({\n        challenge,\n        retry_with: [HEADER_CHALLENGE, HEADER_PROOF_NONCE, HEADER_PROOF_DIGEST],\n      });\n  } catch (err) {\n    opts.onError?.(err, req);\n    throw err;\n  }\n}\n\nasync function redeemAndAdmit(\n  req: FastifyRequest,\n  reply: FastifyReply,\n  opts: BtxAdmissionOpts,\n): Promise<void> {\n  const challengeRaw = headerValue(req, HEADER_CHALLENGE);\n  const nonce = headerValue(req, HEADER_PROOF_NONCE);\n  const digest = headerValue(req, HEADER_PROOF_DIGEST);\n\n  if (!challengeRaw) {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'missing_challenge_header',\n      message: `Retry must include the original challenge in the ${HEADER_CHALLENGE} header (echo-back).`,\n    });\n    return;\n  }\n\n  let challenge: Challenge;\n  try {\n    challenge = JSON.parse(challengeRaw) as Challenge;\n  } catch {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'malformed_challenge_header',\n      message: `${HEADER_CHALLENGE} must be a JSON-encoded Challenge envelope.`,\n    });\n    return;\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 = headerValue(req, HEADER_CHALLENGE_ID);\n  if (idHeader && idHeader !== challenge.challenge_id) {\n    await reply.code(400).header('content-type', 'application/json').send({\n      error: 'challenge_id_mismatch',\n      message: `${HEADER_CHALLENGE_ID} does not match challenge_id in ${HEADER_CHALLENGE}.`,\n    });\n    return;\n  }\n\n  try {\n    const result = await opts.client.redeem(challenge, nonce!, digest!);\n    if (!result.valid) {\n      await reply.code(403).header('content-type', 'application/json').send({\n        valid: false,\n        reason: result.reason,\n        expired: result.expired,\n      });\n      return;\n    }\n    req.btx = { result };\n    opts.onAdmit?.(req, result);\n    // Fall through to the route handler — no explicit reply.send here.\n  } catch (err) {\n    opts.onError?.(err, req);\n    throw err;\n  }\n}\n\nfunction resolve(value: StringOrFn, req: FastifyRequest): string {\n  return typeof value === 'function' ? value(req) : value;\n}\n\n/** Fastify header values can be string | string[] | undefined; normalize to string. */\nfunction headerValue(req: FastifyRequest, name: string): string | undefined {\n  const v = req.headers[name];\n  if (Array.isArray(v)) return v[0];\n  return v;\n}\n"]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@btx-tools/middleware-fastify",
+  "version": "0.1.0",
+  "description": "Fastify plugin for @btx-tools/challenges-sdk — drop-in BTX service-challenge admission gate",
+  "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",
+    "fastify": "^4.0.0 || ^5.0.0"
+  },
+  "dependencies": {
+    "fastify-plugin": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "fastify": "^5.0.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",
+    "fastify",
+    "middleware",
+    "plugin",
+    "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-fastify"
+  },
+  "homepage": "https://github.com/btx-tools/btx-challenges-sdk/tree/main/packages/middleware-fastify#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\""
+  }
+}