kite-x402-hono 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +4 -0
- package/README.md +14 -0
- package/README.zh-CN.md +6 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/middleware/structuredErrorLogger.d.ts +9 -0
- package/dist/middleware/structuredErrorLogger.js +29 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
- Review PR #62: export a structured JSON error handler for explicit `app.onError` registration, with validated request IDs, generic no-store 500 responses, optional server-only stacks, and isolated logging failures.
|
|
6
|
+
|
|
3
7
|
## 0.5.0
|
|
4
8
|
|
|
5
9
|
- Integrate reviewed PRs #52–#61, including fee snapshot isolation, atomic response cache updates, and per-network settlement reconciliation.
|
package/README.md
CHANGED
|
@@ -343,3 +343,17 @@ Socket peer addresses are used by default (`TRUST_PROXY_HEADERS=false`). Direct
|
|
|
343
343
|
The next release includes optional library components and security corrections described in [the PR review report](docs/pr-review-2026-11-04.md). Utilities require explicit integration; adding a helper does not automatically enable dynamic prices, cached payment authorization, webhooks, sessions, distributed limiting or response compression. Forwarded client IP headers are disabled by default; configure trusted proxies explicitly when deploying behind an ingress.
|
|
344
344
|
|
|
345
345
|
Review and integration contracts for PRs #52–#61: [November review](docs/pr-review-2026-11-06.md). New utilities require explicit integration.
|
|
346
|
+
|
|
347
|
+
### Optional structured error handler
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
import { Hono } from "hono";
|
|
351
|
+
import { structuredErrorLogger } from "kite-x402-hono";
|
|
352
|
+
|
|
353
|
+
const app = new Hono();
|
|
354
|
+
app.onError(structuredErrorLogger({ sink: (line) => console.error(line) }));
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Register with `app.onError`, not `app.use`: Hono handles route exceptions internally before `next()` returns. This opt-in handler replaces the application's previous error handler. Every caught exception becomes a generic HTTP 500, including thrown HTTP exceptions; return deliberate business responses normally or compose a separate error policy. Existing `createApp()` behavior is unchanged unless you replace its handler explicitly.
|
|
358
|
+
|
|
359
|
+
Valid incoming `X-Request-ID` values are reused; missing/invalid IDs receive a UUID. IDs are correlation labels, not trusted identities. The response contains `{ error: "internal_error", requestId }` and `Cache-Control: no-store`. Logs are JSON; raw error messages are omitted by default. `includeStack: true` includes stacks only in server logs, which may then contain secrets. This handler does not emit `X-Trace-ID`. A custom outer request-ID middleware should preserve the response ID instead of replacing it.
|
package/README.zh-CN.md
CHANGED
|
@@ -239,3 +239,9 @@ AI 工具参与了开发;BrK 审核并负责此贡献。项目自己的 Wrappe
|
|
|
239
239
|
下一版本包含的可选组件、安全修正与使用边界见[PR 审查报告](docs/pr-review-2026-11-04.md)。这些工具需要显式接入,不会自动启用动态定价、付款验证缓存、Webhook、会话、分布式限流或响应压缩。默认使用连接 IP;部署在反向代理后时需显式配置可信代理。
|
|
240
240
|
|
|
241
241
|
PR #52–#61 的审查结果与使用约定见 [11 月审查记录](docs/pr-review-2026-11-06.md)。新增工具需要显式接入应用。
|
|
242
|
+
|
|
243
|
+
### 可选的结构化错误处理器
|
|
244
|
+
|
|
245
|
+
通过 `app.onError(structuredErrorLogger({ sink: console.error }))` 显式注册;不要使用 `app.use`,因为 Hono 会先处理路由异常。该工具从包根目录导出,注册会替换原有异常处理器,所有捕获异常统一返回 500(包括抛出的 HTTP 异常);业务响应应正常返回,或另行组合异常策略。默认 `createApp()` 行为保持不变。
|
|
246
|
+
|
|
247
|
+
响应为 `{ error: "internal_error", requestId }`,禁止缓存。沿用经过校验的 `X-Request-ID`,缺失或非法时生成 UUID;不再新增 `X-Trace-ID`。服务端输出 JSON 日志,默认不记录原始异常消息。`includeStack: true` 仅在服务端日志中加入堆栈,日志可能因此包含敏感信息。外层自定义请求 ID 中间件应保留错误响应已有的 ID。
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { ErrorHandler } from "hono";
|
|
2
|
+
export interface StructuredErrorLoggerOptions {
|
|
3
|
+
/** Include stack traces in server logs only. Logs may contain sensitive data. */
|
|
4
|
+
includeStack?: boolean;
|
|
5
|
+
sink?: (line: string) => void;
|
|
6
|
+
}
|
|
7
|
+
/** Register with app.onError(); Hono handles exceptions before next() returns. */
|
|
8
|
+
export declare function structuredErrorLogger(options?: StructuredErrorLoggerOptions): ErrorHandler;
|
|
9
|
+
export default structuredErrorLogger;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
const validId = /^[A-Za-z0-9._~-]{1,128}$/;
|
|
2
|
+
/** Register with app.onError(); Hono handles exceptions before next() returns. */
|
|
3
|
+
export function structuredErrorLogger(options = {}) {
|
|
4
|
+
const sink = options.sink ?? console.error;
|
|
5
|
+
return (err, c) => {
|
|
6
|
+
const candidate = c.req.header("x-request-id");
|
|
7
|
+
const requestId = candidate && validId.test(candidate) ? candidate : crypto.randomUUID();
|
|
8
|
+
// Arbitrary error.status/code/message values are never public response data.
|
|
9
|
+
const timestamp = new Date().toISOString();
|
|
10
|
+
try {
|
|
11
|
+
sink(JSON.stringify({
|
|
12
|
+
level: "error",
|
|
13
|
+
timestamp,
|
|
14
|
+
requestId,
|
|
15
|
+
status: 500,
|
|
16
|
+
error: "internal_error",
|
|
17
|
+
...(options.includeStack && { stack: err.stack }),
|
|
18
|
+
}));
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
// A broken logging sink must not prevent the error response.
|
|
22
|
+
}
|
|
23
|
+
return c.json({ error: "internal_error", requestId }, 500, {
|
|
24
|
+
"x-request-id": requestId,
|
|
25
|
+
"cache-control": "no-store",
|
|
26
|
+
});
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
export default structuredErrorLogger;
|