@t-0/provider-sdk 1.1.30 → 1.1.32

package/README.md

@@ -27,9 +27,7 @@ Implement the `ProviderService` interface to receive callbacks from the T-0 Netw
 ```ts
 import http from "node:http";
 import {
-  createService,
-  nodeAdapter,
-  signatureValidation,
+  createHandler,
   ProviderService,
   PayoutRequest,
   PayoutResponse,
@@ -41,28 +39,40 @@ import {
 const networkPublicKey = process.env.NETWORK_PUBLIC_KEY!;
 
 const server = http.createServer(
-  signatureValidation(
-    nodeAdapter(
-      createService(networkPublicKey, (r) => {
-        r.service(ProviderService, {
-          async payOut(req: PayoutRequest, ctx: HandlerContext): Promise<PayoutResponse> {
-            // Handle payout requests from counterparts
-            return { result: { case: "accepted", value: {} } } as PayoutResponse;
-          },
-          async updatePayment(req: UpdatePaymentRequest, ctx: HandlerContext): Promise<UpdatePaymentResponse> {
-            // Handle payment status updates
-            return {} as UpdatePaymentResponse;
-          },
-        });
-      })
-    )
-  )
+  createHandler(networkPublicKey, (r) => {
+    r.service(ProviderService, {
+      async payOut(req: PayoutRequest, ctx: HandlerContext): Promise<PayoutResponse> {
+        // Handle payout requests from counterparts
+        return { result: { case: "accepted", value: {} } } as PayoutResponse;
+      },
+      async updatePayment(req: UpdatePaymentRequest, ctx: HandlerContext): Promise<UpdatePaymentResponse> {
+        // Handle payment status updates
+        return {} as UpdatePaymentResponse;
+      },
+    });
+  })
 );
 
 server.listen(3000);
 ```
 
-The middleware chain: `signatureValidation` captures raw request bytes for hashing, `nodeAdapter` bridges the RPC transport to Node.js HTTP, and `createService` registers your handlers with signature verification.
+`createHandler` composes the full middleware chain in one call: signature validation (raw byte capture), Connect-Node adapter, and service registration with signature verification.
+
+<details>
+<summary>Manual composition (advanced)</summary>
+
+For cases where you need to customize the middleware chain, the individual components are also exported:
+
+```ts
+import { createService, nodeAdapter, signatureValidation } from "@t-0/provider-sdk";
+
+const server = http.createServer(
+  signatureValidation(nodeAdapter(createService(networkPublicKey, registerRoutes)))
+);
+```
+
+`signatureValidation` captures raw request bytes for hashing, `nodeAdapter` bridges the RPC transport to Node.js HTTP, and `createService` registers your handlers with signature verification.
+</details>
 
 ### Standalone Signature Verification
 
@@ -70,7 +80,7 @@ For frameworks that don't use Node's `http.createServer` (Effect, Koa, Fastify,
 
 ```ts
 import { fromBinary, toBinary } from "@bufbuild/protobuf";
-import { createRequestVerifier, PayoutRequestSchema, PayoutResponseSchema } from "@t-0/provider-sdk";
+import { createRequestVerifier, rejectRequest, PayoutRequestSchema, PayoutResponseSchema } from "@t-0/provider-sdk";
 
 const verify = createRequestVerifier({
   networkPublicKey: process.env.NETWORK_PUBLIC_KEY!,
@@ -86,10 +96,10 @@ function handleRequest(rawBody: Uint8Array, headers: Record<string, string>) {
   });
 
   if (!result.valid) {
-    // result.reason is one of: 'invalid_timestamp', 'timestamp_out_of_range',
-    // 'invalid_public_key', 'unknown_public_key', 'invalid_signature_format',
-    // 'signature_failed'
-    return errorResponse(result.reason);
+    // rejectRequest maps the failure reason to a well-formed HTTP error
+    // with status (400 or 401), Content-Type header, and JSON body.
+    const rejected = rejectRequest(result.reason);
+    return errorResponse(rejected.status, rejected.headers, rejected.body);
   }
 
   // Deserialize the Protobuf request (same raw bytes you verified)
@@ -110,7 +120,7 @@ The lower-level primitives are also exported individually: `verifySignature`, `c
 - **Raw body bytes only.** Pass the exact wire bytes to the verifier — no body parsers, no auto-decompression, never re-serialized protobuf. Protobuf encoding is not canonical; re-encoding produces different bytes and breaks verification.
 - **Pass `Uint8Array`, not `ArrayBuffer`.** If your framework gives you an `ArrayBuffer` (e.g. `request.arrayBuffer()`), wrap it: `new Uint8Array(buf)`.
 - **Header case.** `NetworkHeaders` enum values are title-case (`X-Signature`), but Node lowercases incoming headers. Look up headers by lowercase name: `headers["x-signature"]`.
-- **Wire format is binary protobuf.** Requests and successful responses use `Content-Type: application/proto`. Deserialize with `fromBinary()`, serialize with `toBinary()` from `@bufbuild/protobuf`. For errors, return a bare HTTP status code with no body (`401` for auth failures, `403` for permission errors). Success responses **must** include `Content-Type: application/proto`.
+- **Wire format is binary protobuf.** Requests and successful responses use `Content-Type: application/proto`. Deserialize with `fromBinary()`, serialize with `toBinary()` from `@bufbuild/protobuf`. For verification errors, use `rejectRequest(result.reason)` to get the correct HTTP status, headers, and JSON body. Success responses **must** include `Content-Type: application/proto`.
 - **Health endpoint.** The T-0 Network probes `/grpc.health.v1.Health/Check` on every endpoint. The probe is signed. Standalone integrations must route this path and return a valid health response. See [`docs/HEALTH_SERVICE.md`](../../docs/HEALTH_SERVICE.md) for the wire contract.
 - **`VerifyRequestFailure` is an open union.** New reason values may be added without a major version bump. Handle unknown reasons as generic failures.
 

package/lib/cjs/common/crypto/index.d.ts

@@ -1,5 +1,5 @@
 export { verifySignature } from './verify.js';
 export { keccak256, computeDigest } from './hash.js';
 export { parsePublicKey, publicKeysEqual } from './keys.js';
-export { createRequestVerifier, DEFAULT_TOLERANCE_MS } from './request.js';
-export type { CreateVerifierOptions, VerifyRequest, VerifyRequestResult, VerifyRequestFailure, RequestVerifier } from './request.js';
+export { createRequestVerifier, DEFAULT_TOLERANCE_MS, rejectRequest } from './request.js';
+export type { CreateVerifierOptions, VerifyRequest, VerifyRequestResult, VerifyRequestFailure, RequestVerifier, RejectedRequest } from './request.js';

package/lib/cjs/common/crypto/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TOLERANCE_MS = exports.createRequestVerifier = exports.publicKeysEqual = exports.parsePublicKey = exports.computeDigest = exports.keccak256 = exports.verifySignature = void 0;
+exports.rejectRequest = exports.DEFAULT_TOLERANCE_MS = exports.createRequestVerifier = exports.publicKeysEqual = exports.parsePublicKey = exports.computeDigest = exports.keccak256 = exports.verifySignature = void 0;
 var verify_js_1 = require("./verify.js");
 Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return verify_js_1.verifySignature; } });
 var hash_js_1 = require("./hash.js");
@@ -12,3 +12,4 @@ Object.defineProperty(exports, "publicKeysEqual", { enumerable: true, get: funct
 var request_js_1 = require("./request.js");
 Object.defineProperty(exports, "createRequestVerifier", { enumerable: true, get: function () { return request_js_1.createRequestVerifier; } });
 Object.defineProperty(exports, "DEFAULT_TOLERANCE_MS", { enumerable: true, get: function () { return request_js_1.DEFAULT_TOLERANCE_MS; } });
+Object.defineProperty(exports, "rejectRequest", { enumerable: true, get: function () { return request_js_1.rejectRequest; } });

package/lib/cjs/common/crypto/request.d.ts

@@ -18,3 +18,9 @@ export type VerifyRequestResult = {
 };
 export type RequestVerifier = (req: VerifyRequest) => VerifyRequestResult;
 export declare function createRequestVerifier(opts: CreateVerifierOptions): RequestVerifier;
+export interface RejectedRequest {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function rejectRequest(reason: VerifyRequestFailure): RejectedRequest;

package/lib/cjs/common/crypto/request.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_TOLERANCE_MS = void 0;
 exports.createRequestVerifier = createRequestVerifier;
+exports.rejectRequest = rejectRequest;
 const verify_js_1 = require("./verify.js");
 const hash_js_1 = require("./hash.js");
 const keys_js_1 = require("./keys.js");
@@ -49,3 +50,53 @@ function createRequestVerifier(opts) {
         return { valid: true };
     };
 }
+function rejectRequest(reason) {
+    let status;
+    let code;
+    let message;
+    switch (reason) {
+        case 'invalid_timestamp':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid signature timestamp';
+            break;
+        case 'timestamp_out_of_range':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Signature timestamp out of range';
+            break;
+        case 'invalid_public_key':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid public key format';
+            break;
+        case 'unknown_public_key':
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Unknown public key';
+            break;
+        case 'invalid_signature_format':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid signature format';
+            break;
+        case 'signature_failed':
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Signature verification failed';
+            break;
+        default: {
+            const _exhaustive = reason;
+            void _exhaustive;
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Request verification failed';
+            break;
+        }
+    }
+    return {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code, message }),
+    };
+}

package/lib/cjs/common/node.d.ts

@@ -1,3 +1,5 @@
 import type * as http from "node:http";
+import { type CreateServiceOptions, type Router } from "./service.js";
 export type NodeHandlerFn = (request: http.IncomingMessage, response: http.ServerResponse) => void;
 export declare const signatureValidation: (next: NodeHandlerFn) => NodeHandlerFn;
+export declare const createHandler: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => NodeHandlerFn;

package/lib/cjs/common/node.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.signatureValidation = void 0;
+exports.createHandler = exports.signatureValidation = void 0;
 const sha3_js_1 = require("@noble/hashes/sha3.js");
+const connect_node_1 = require("@connectrpc/connect-node");
+const service_js_1 = require("./service.js");
 const signatureValidation = (next) => (req, resp) => {
     const hasher = sha3_js_1.keccak_256.create();
     req.hasher = hasher;
@@ -13,3 +15,5 @@ const signatureValidation = (next) => (req, resp) => {
     next(req, resp);
 };
 exports.signatureValidation = signatureValidation;
+const createHandler = (networkPublicKey, registerRoutes, options) => (0, exports.signatureValidation)((0, connect_node_1.connectNodeAdapter)((0, service_js_1.createService)(networkPublicKey, registerRoutes, options)));
+exports.createHandler = createHandler;

package/lib/cjs/common/service.d.ts

@@ -25,7 +25,7 @@ export interface CreateServiceOptions {
     version?: string;
 }
 export declare const REQUEST_VALIDITY_MILLIS = 60000;
-interface Router {
+export interface Router {
     service: <T extends DescService, I extends ServiceImpl<T>>(service: T, implementation: I) => void;
 }
 export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => {
@@ -34,4 +34,3 @@ export declare const createService: (networkPublicKey: string | Buffer, register
     grpcWeb: boolean;
     contextValues: (req: any) => import("@connectrpc/connect").ContextValues;
 };
-export {};

package/lib/cjs/service/node.d.ts

@@ -1 +1,5 @@
-export * from "../common/node.js";
+import { createHandler as createHandlerCommon } from "../common/node.js";
+import type { Router, CreateServiceOptions } from "../common/service.js";
+export { signatureValidation } from "../common/node.js";
+export type { NodeHandlerFn } from "../common/node.js";
+export declare const createHandler: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => ReturnType<typeof createHandlerCommon>;

package/lib/cjs/service/node.js

@@ -1,17 +1,9 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("../common/node.js"), exports);
+exports.createHandler = exports.signatureValidation = void 0;
+const node_js_1 = require("../common/node.js");
+const version_js_1 = require("../version.js");
+var node_js_2 = require("../common/node.js");
+Object.defineProperty(exports, "signatureValidation", { enumerable: true, get: function () { return node_js_2.signatureValidation; } });
+const createHandler = (networkPublicKey, registerRoutes, options) => (0, node_js_1.createHandler)(networkPublicKey, registerRoutes, { ...options, version: options?.version ?? version_js_1.SDK_VERSION });
+exports.createHandler = createHandler;

package/lib/cjs/service/service.d.ts

@@ -1,12 +1,4 @@
-import { type CreateServiceOptions } from "../common/service.js";
-export type { CreateServiceOptions } from "../common/service.js";
+import { createService as createServiceCommon, type CreateServiceOptions, type Router } from "../common/service.js";
+export type { CreateServiceOptions, Router } from "../common/service.js";
 export { REQUEST_VALIDITY_MILLIS } from "../common/service.js";
-interface Router {
-    service: <T extends import("@bufbuild/protobuf").DescService, I extends import("@connectrpc/connect").ServiceImpl<T>>(service: T, implementation: I) => void;
-}
-export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => {
-    routes: (router: import("@connectrpc/connect").ConnectRouter) => void;
-    interceptors: import("@connectrpc/connect").Interceptor[];
-    grpcWeb: boolean;
-    contextValues: (req: any) => import("@connectrpc/connect").ContextValues;
-};
+export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => ReturnType<typeof createServiceCommon>;

package/lib/cjs/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.1.30";
+export declare const SDK_VERSION = "1.1.32";

package/lib/cjs/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 // SDK semantic version. Bumped in lockstep with all other SDKs by the
 // release.yaml workflow.
-exports.SDK_VERSION = "1.1.30";
+exports.SDK_VERSION = "1.1.32";

package/lib/esm/common/crypto/index.d.ts

@@ -1,5 +1,5 @@
 export { verifySignature } from './verify.js';
 export { keccak256, computeDigest } from './hash.js';
 export { parsePublicKey, publicKeysEqual } from './keys.js';
-export { createRequestVerifier, DEFAULT_TOLERANCE_MS } from './request.js';
-export type { CreateVerifierOptions, VerifyRequest, VerifyRequestResult, VerifyRequestFailure, RequestVerifier } from './request.js';
+export { createRequestVerifier, DEFAULT_TOLERANCE_MS, rejectRequest } from './request.js';
+export type { CreateVerifierOptions, VerifyRequest, VerifyRequestResult, VerifyRequestFailure, RequestVerifier, RejectedRequest } from './request.js';

package/lib/esm/common/crypto/index.js

@@ -1,4 +1,4 @@
 export { verifySignature } from './verify.js';
 export { keccak256, computeDigest } from './hash.js';
 export { parsePublicKey, publicKeysEqual } from './keys.js';
-export { createRequestVerifier, DEFAULT_TOLERANCE_MS } from './request.js';
+export { createRequestVerifier, DEFAULT_TOLERANCE_MS, rejectRequest } from './request.js';

package/lib/esm/common/crypto/request.d.ts

@@ -18,3 +18,9 @@ export type VerifyRequestResult = {
 };
 export type RequestVerifier = (req: VerifyRequest) => VerifyRequestResult;
 export declare function createRequestVerifier(opts: CreateVerifierOptions): RequestVerifier;
+export interface RejectedRequest {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function rejectRequest(reason: VerifyRequestFailure): RejectedRequest;

package/lib/esm/common/crypto/request.js

@@ -45,3 +45,53 @@ export function createRequestVerifier(opts) {
         return { valid: true };
     };
 }
+export function rejectRequest(reason) {
+    let status;
+    let code;
+    let message;
+    switch (reason) {
+        case 'invalid_timestamp':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid signature timestamp';
+            break;
+        case 'timestamp_out_of_range':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Signature timestamp out of range';
+            break;
+        case 'invalid_public_key':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid public key format';
+            break;
+        case 'unknown_public_key':
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Unknown public key';
+            break;
+        case 'invalid_signature_format':
+            status = 400;
+            code = 'invalid_argument';
+            message = 'Invalid signature format';
+            break;
+        case 'signature_failed':
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Signature verification failed';
+            break;
+        default: {
+            const _exhaustive = reason;
+            void _exhaustive;
+            status = 401;
+            code = 'unauthenticated';
+            message = 'Request verification failed';
+            break;
+        }
+    }
+    return {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code, message }),
+    };
+}

package/lib/esm/common/node.d.ts

@@ -1,3 +1,5 @@
 import type * as http from "node:http";
+import { type CreateServiceOptions, type Router } from "./service.js";
 export type NodeHandlerFn = (request: http.IncomingMessage, response: http.ServerResponse) => void;
 export declare const signatureValidation: (next: NodeHandlerFn) => NodeHandlerFn;
+export declare const createHandler: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => NodeHandlerFn;

package/lib/esm/common/node.js

@@ -1,4 +1,6 @@
 import { keccak_256 } from "@noble/hashes/sha3.js";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { createService } from "./service.js";
 export const signatureValidation = (next) => (req, resp) => {
     const hasher = keccak_256.create();
     req.hasher = hasher;
@@ -9,3 +11,4 @@ export const signatureValidation = (next) => (req, resp) => {
     });
     next(req, resp);
 };
+export const createHandler = (networkPublicKey, registerRoutes, options) => signatureValidation(connectNodeAdapter(createService(networkPublicKey, registerRoutes, options)));

package/lib/esm/common/service.d.ts

@@ -25,7 +25,7 @@ export interface CreateServiceOptions {
     version?: string;
 }
 export declare const REQUEST_VALIDITY_MILLIS = 60000;
-interface Router {
+export interface Router {
     service: <T extends DescService, I extends ServiceImpl<T>>(service: T, implementation: I) => void;
 }
 export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => {
@@ -34,4 +34,3 @@ export declare const createService: (networkPublicKey: string | Buffer, register
     grpcWeb: boolean;
     contextValues: (req: any) => import("@connectrpc/connect").ContextValues;
 };
-export {};

package/lib/esm/service/node.d.ts

@@ -1 +1,5 @@
-export * from "../common/node.js";
+import { createHandler as createHandlerCommon } from "../common/node.js";
+import type { Router, CreateServiceOptions } from "../common/service.js";
+export { signatureValidation } from "../common/node.js";
+export type { NodeHandlerFn } from "../common/node.js";
+export declare const createHandler: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => ReturnType<typeof createHandlerCommon>;

package/lib/esm/service/node.js

@@ -1 +1,4 @@
-export * from "../common/node.js";
+import { createHandler as createHandlerCommon } from "../common/node.js";
+import { SDK_VERSION } from "../version.js";
+export { signatureValidation } from "../common/node.js";
+export const createHandler = (networkPublicKey, registerRoutes, options) => createHandlerCommon(networkPublicKey, registerRoutes, { ...options, version: options?.version ?? SDK_VERSION });

package/lib/esm/service/service.d.ts

@@ -1,12 +1,4 @@
-import { type CreateServiceOptions } from "../common/service.js";
-export type { CreateServiceOptions } from "../common/service.js";
+import { createService as createServiceCommon, type CreateServiceOptions, type Router } from "../common/service.js";
+export type { CreateServiceOptions, Router } from "../common/service.js";
 export { REQUEST_VALIDITY_MILLIS } from "../common/service.js";
-interface Router {
-    service: <T extends import("@bufbuild/protobuf").DescService, I extends import("@connectrpc/connect").ServiceImpl<T>>(service: T, implementation: I) => void;
-}
-export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => {
-    routes: (router: import("@connectrpc/connect").ConnectRouter) => void;
-    interceptors: import("@connectrpc/connect").Interceptor[];
-    grpcWeb: boolean;
-    contextValues: (req: any) => import("@connectrpc/connect").ContextValues;
-};
+export declare const createService: (networkPublicKey: string | Buffer, registerRoutes: (router: Router) => void, options?: CreateServiceOptions) => ReturnType<typeof createServiceCommon>;

package/lib/esm/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "1.1.30";
+export declare const SDK_VERSION = "1.1.32";

package/lib/esm/version.js

@@ -1,3 +1,3 @@
 // SDK semantic version. Bumped in lockstep with all other SDKs by the
 // release.yaml workflow.
-export const SDK_VERSION = "1.1.30";
+export const SDK_VERSION = "1.1.32";