@usebetterdev/audit-hono 0.4.0-beta.1

package/README.md

@@ -0,0 +1,152 @@
+# @usebetterdev/audit-hono
+
+Hono middleware for [`@usebetterdev/audit-core`](../core). Automatically extracts actor identity from incoming requests and makes it available to audit logging via `AsyncLocalStorage`.
+
+## Installation
+
+```bash
+pnpm add @usebetterdev/audit-hono @usebetterdev/audit-core
+```
+
+## Quick start
+
+```ts
+import { Hono } from "hono";
+import { betterAudit } from "@usebetterdev/audit-core";
+import { betterAuditHono } from "@usebetterdev/audit-hono";
+
+const audit = betterAudit({
+  database: { writeLog: async (log) => console.log(log) },
+  auditTables: ["users", "orders"],
+});
+
+const app = new Hono();
+
+// Use the middleware — by default it reads the `sub` claim
+// from the Authorization: Bearer <jwt> header.
+app.use("*", betterAuditHono(audit));
+
+app.post("/users", async (c) => {
+  // actorId is automatically attached from the JWT
+  await audit.captureLog({
+    tableName: "users",
+    operation: "INSERT",
+    recordId: "user-42",
+    after: { name: "Alice" },
+  });
+  return c.json({ id: "user-42" }, 201);
+});
+```
+
+## Actor extraction
+
+The middleware resolves the current actor (the user or service making the request) and stores it in `AuditContext.actorId`. Every log captured during that request automatically includes the actor.
+
+### Default: JWT Bearer token
+
+With no options, the middleware decodes the `sub` claim from the `Authorization: Bearer <jwt>` header. The token is decoded **without** signature verification — that is the auth layer's responsibility.
+
+```ts
+app.use("*", betterAuditHono(audit));
+// Authorization: Bearer eyJ...  →  actorId = jwt.sub
+```
+
+### Custom JWT claim
+
+Extract a different claim by providing a custom extractor:
+
+```ts
+import { fromBearerToken } from "@usebetterdev/audit-core";
+
+app.use(
+  "*",
+  betterAuditHono(audit, {
+    extractor: { actor: fromBearerToken("user_id") },
+  }),
+);
+```
+
+### Header-based extraction
+
+Use `fromHeader` when the actor identity is passed as a plain request header (common behind API gateways):
+
+```ts
+import { fromHeader } from "@usebetterdev/audit-core";
+
+app.use(
+  "*",
+  betterAuditHono(audit, {
+    extractor: { actor: fromHeader("x-user-id") },
+  }),
+);
+```
+
+### Cookie-based extraction
+
+Use `fromCookie` for session-based auth where the actor ID lives in a cookie:
+
+```ts
+import { fromCookie } from "@usebetterdev/audit-core";
+
+app.use(
+  "*",
+  betterAuditHono(audit, {
+    extractor: { actor: fromCookie("session_id") },
+  }),
+);
+```
+
+### Custom extractor function
+
+Write your own `ValueExtractor` for full control. It receives the raw `Request` and returns a string or `undefined`:
+
+```ts
+app.use(
+  "*",
+  betterAuditHono(audit, {
+    extractor: {
+      actor: async (request) => {
+        const apiKey = request.headers.get("x-api-key");
+        if (!apiKey) {
+          return undefined;
+        }
+        // Look up the API key owner
+        const owner = await resolveApiKeyOwner(apiKey);
+        return owner?.id;
+      },
+    },
+  }),
+);
+```
+
+## Error handling
+
+Extraction errors never break the request. By default the middleware **fails open** — if an extractor throws, the request proceeds without audit context.
+
+Use `onError` to log or report extraction failures:
+
+```ts
+app.use(
+  "*",
+  betterAuditHono(audit, {
+    onError: (error) => console.error("Audit extraction failed:", error),
+  }),
+);
+```
+
+## API
+
+### `betterAuditHono(audit, options?)`
+
+Convenience wrapper that returns a Hono middleware. Equivalent to `createHonoMiddleware`.
+
+### `createHonoMiddleware(audit, options?)`
+
+Creates a Hono-compatible middleware function.
+
+**Options:**
+
+| Option      | Type                          | Description                                            |
+| ----------- | ----------------------------- | ------------------------------------------------------ |
+| `extractor` | `ContextExtractor`            | Actor extractor config. Defaults to JWT `sub` claim.   |
+| `onError`   | `(error: unknown) => void`    | Called when an extractor throws. Defaults to no-op.    |

package/dist/index.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  betterAuditHono: () => betterAuditHono,
+  createHonoMiddleware: () => createHonoMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_audit_core = require("@usebetterdev/audit-core");
+var defaultExtractor = {
+  actor: (0, import_audit_core.fromBearerToken)("sub")
+};
+function createHonoMiddleware(options = {}) {
+  const extractor = options.extractor ?? defaultExtractor;
+  const handlerOptions = {};
+  if (options.onError) {
+    handlerOptions.onError = options.onError;
+  }
+  return async (context, next) => {
+    await (0, import_audit_core.handleMiddleware)(extractor, context.req.raw, next, handlerOptions);
+    return void 0;
+  };
+}
+function betterAuditHono(options = {}) {
+  return createHonoMiddleware(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  betterAuditHono,
+  createHonoMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  AuditContext,\n  ContextExtractor,\n  MiddlewareHandlerOptions,\n} from \"@usebetterdev/audit-core\";\nimport {\n  handleMiddleware,\n  fromBearerToken,\n} from \"@usebetterdev/audit-core\";\n\nexport interface HonoContextLike {\n  req: { raw: Request };\n}\n\nexport type HonoMiddleware = (\n  context: HonoContextLike,\n  next: () => Promise<void>,\n) => Promise<Response | void>;\n\nexport interface CreateHonoMiddlewareOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n/**\n * Creates a Hono-compatible middleware that populates audit context\n * via AsyncLocalStorage on every request.\n *\n * Delegates to the shared `handleMiddleware()` from audit-core,\n * which all framework adapters share.\n *\n * The middleware is non-blocking: if context extraction fails, the\n * request proceeds without audit context (fail open).\n */\nexport function createHonoMiddleware(\n  options: CreateHonoMiddlewareOptions = {},\n): HonoMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const handlerOptions: MiddlewareHandlerOptions = {};\n  if (options.onError) {\n    handlerOptions.onError = options.onError;\n  }\n\n  return async (context, next) => {\n    await handleMiddleware(extractor, context.req.raw, next, handlerOptions);\n    return undefined;\n  };\n}\n\n/**\n * Convenience wrapper: `app.use('*', betterAuditHono())`.\n *\n * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).\n * Pass options to customize extraction.\n */\nexport function betterAuditHono(\n  options: CreateHonoMiddlewareOptions = {},\n): HonoMiddleware {\n  return createHonoMiddleware(options);\n}\n\nexport type { AuditContext, ContextExtractor };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,wBAGO;AAmBP,IAAM,mBAAqC;AAAA,EACzC,WAAO,mCAAgB,KAAK;AAC9B;AAYO,SAAS,qBACd,UAAuC,CAAC,GACxB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,iBAA2C,CAAC;AAClD,MAAI,QAAQ,SAAS;AACnB,mBAAe,UAAU,QAAQ;AAAA,EACnC;AAEA,SAAO,OAAO,SAAS,SAAS;AAC9B,cAAM,oCAAiB,WAAW,QAAQ,IAAI,KAAK,MAAM,cAAc;AACvE,WAAO;AAAA,EACT;AACF;AAQO,SAAS,gBACd,UAAuC,CAAC,GACxB;AAChB,SAAO,qBAAqB,OAAO;AACrC;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { ContextExtractor } from '@usebetterdev/audit-core';
+export { AuditContext, ContextExtractor } from '@usebetterdev/audit-core';
+
+interface HonoContextLike {
+    req: {
+        raw: Request;
+    };
+}
+type HonoMiddleware = (context: HonoContextLike, next: () => Promise<void>) => Promise<Response | void>;
+interface CreateHonoMiddlewareOptions {
+    /** Context extractor for pulling actor identity from the request. */
+    extractor?: ContextExtractor;
+    /** Called when an extractor throws. Defaults to silent fail-open. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Creates a Hono-compatible middleware that populates audit context
+ * via AsyncLocalStorage on every request.
+ *
+ * Delegates to the shared `handleMiddleware()` from audit-core,
+ * which all framework adapters share.
+ *
+ * The middleware is non-blocking: if context extraction fails, the
+ * request proceeds without audit context (fail open).
+ */
+declare function createHonoMiddleware(options?: CreateHonoMiddlewareOptions): HonoMiddleware;
+/**
+ * Convenience wrapper: `app.use('*', betterAuditHono())`.
+ *
+ * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).
+ * Pass options to customize extraction.
+ */
+declare function betterAuditHono(options?: CreateHonoMiddlewareOptions): HonoMiddleware;
+
+export { type CreateHonoMiddlewareOptions, type HonoContextLike, type HonoMiddleware, betterAuditHono, createHonoMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { ContextExtractor } from '@usebetterdev/audit-core';
+export { AuditContext, ContextExtractor } from '@usebetterdev/audit-core';
+
+interface HonoContextLike {
+    req: {
+        raw: Request;
+    };
+}
+type HonoMiddleware = (context: HonoContextLike, next: () => Promise<void>) => Promise<Response | void>;
+interface CreateHonoMiddlewareOptions {
+    /** Context extractor for pulling actor identity from the request. */
+    extractor?: ContextExtractor;
+    /** Called when an extractor throws. Defaults to silent fail-open. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Creates a Hono-compatible middleware that populates audit context
+ * via AsyncLocalStorage on every request.
+ *
+ * Delegates to the shared `handleMiddleware()` from audit-core,
+ * which all framework adapters share.
+ *
+ * The middleware is non-blocking: if context extraction fails, the
+ * request proceeds without audit context (fail open).
+ */
+declare function createHonoMiddleware(options?: CreateHonoMiddlewareOptions): HonoMiddleware;
+/**
+ * Convenience wrapper: `app.use('*', betterAuditHono())`.
+ *
+ * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).
+ * Pass options to customize extraction.
+ */
+declare function betterAuditHono(options?: CreateHonoMiddlewareOptions): HonoMiddleware;
+
+export { type CreateHonoMiddlewareOptions, type HonoContextLike, type HonoMiddleware, betterAuditHono, createHonoMiddleware };

package/dist/index.js

@@ -0,0 +1,27 @@
+// src/index.ts
+import {
+  handleMiddleware,
+  fromBearerToken
+} from "@usebetterdev/audit-core";
+var defaultExtractor = {
+  actor: fromBearerToken("sub")
+};
+function createHonoMiddleware(options = {}) {
+  const extractor = options.extractor ?? defaultExtractor;
+  const handlerOptions = {};
+  if (options.onError) {
+    handlerOptions.onError = options.onError;
+  }
+  return async (context, next) => {
+    await handleMiddleware(extractor, context.req.raw, next, handlerOptions);
+    return void 0;
+  };
+}
+function betterAuditHono(options = {}) {
+  return createHonoMiddleware(options);
+}
+export {
+  betterAuditHono,
+  createHonoMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n  AuditContext,\n  ContextExtractor,\n  MiddlewareHandlerOptions,\n} from \"@usebetterdev/audit-core\";\nimport {\n  handleMiddleware,\n  fromBearerToken,\n} from \"@usebetterdev/audit-core\";\n\nexport interface HonoContextLike {\n  req: { raw: Request };\n}\n\nexport type HonoMiddleware = (\n  context: HonoContextLike,\n  next: () => Promise<void>,\n) => Promise<Response | void>;\n\nexport interface CreateHonoMiddlewareOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n/**\n * Creates a Hono-compatible middleware that populates audit context\n * via AsyncLocalStorage on every request.\n *\n * Delegates to the shared `handleMiddleware()` from audit-core,\n * which all framework adapters share.\n *\n * The middleware is non-blocking: if context extraction fails, the\n * request proceeds without audit context (fail open).\n */\nexport function createHonoMiddleware(\n  options: CreateHonoMiddlewareOptions = {},\n): HonoMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const handlerOptions: MiddlewareHandlerOptions = {};\n  if (options.onError) {\n    handlerOptions.onError = options.onError;\n  }\n\n  return async (context, next) => {\n    await handleMiddleware(extractor, context.req.raw, next, handlerOptions);\n    return undefined;\n  };\n}\n\n/**\n * Convenience wrapper: `app.use('*', betterAuditHono())`.\n *\n * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).\n * Pass options to customize extraction.\n */\nexport function betterAuditHono(\n  options: CreateHonoMiddlewareOptions = {},\n): HonoMiddleware {\n  return createHonoMiddleware(options);\n}\n\nexport type { AuditContext, ContextExtractor };\n"],"mappings":";AAKA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAmBP,IAAM,mBAAqC;AAAA,EACzC,OAAO,gBAAgB,KAAK;AAC9B;AAYO,SAAS,qBACd,UAAuC,CAAC,GACxB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,iBAA2C,CAAC;AAClD,MAAI,QAAQ,SAAS;AACnB,mBAAe,UAAU,QAAQ;AAAA,EACnC;AAEA,SAAO,OAAO,SAAS,SAAS;AAC9B,UAAM,iBAAiB,WAAW,QAAQ,IAAI,KAAK,MAAM,cAAc;AACvE,WAAO;AAAA,EACT;AACF;AAQO,SAAS,gBACd,UAAuC,CAAC,GACxB;AAChB,SAAO,qBAAqB,OAAO;AACrC;","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@usebetterdev/audit-hono",
+  "version": "0.4.0-beta.1",
+  "repository": "github:usebetter-dev/usebetter",
+  "bugs": "https://github.com/usebetter-dev/usebetter/issues",
+  "homepage": "https://github.com/usebetter-dev/usebetter#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@usebetterdev/audit-core": "workspace:*"
+  },
+  "peerDependencies": {
+    "hono": ">=4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "hono": "^4.11.9",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2",
+    "vitest": "^2.1.6"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}