@usebetterdev/audit-express 0.5.0-beta.1

package/README.md

@@ -0,0 +1,141 @@
+# @usebetterdev/audit-express
+
+Express 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-express @usebetterdev/audit-core
+```
+
+## Quick start
+
+```ts
+import express from "express";
+import { betterAudit } from "@usebetterdev/audit-core";
+import { betterAuditExpress } from "@usebetterdev/audit-express";
+
+const audit = betterAudit({
+  database: { writeLog: async (log) => console.log(log) },
+  auditTables: ["users", "orders"],
+});
+
+const app = express();
+app.use(express.json());
+
+// Use the middleware — by default it reads the `sub` claim
+// from the Authorization: Bearer <jwt> header.
+app.use(betterAuditExpress());
+
+app.post("/users", async (req, res, next) => {
+  try {
+    // actorId is automatically attached from the JWT
+    await audit.captureLog({
+      tableName: "users",
+      operation: "INSERT",
+      recordId: "user-42",
+      after: { name: "Alice" },
+    });
+    res.status(201).json({ id: "user-42" });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+## 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(betterAuditExpress());
+// 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(betterAuditExpress({ 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(betterAuditExpress({ 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(betterAuditExpress({ extractor: { actor: fromCookie("session_id") } }));
+```
+
+### Custom extractor function
+
+Write your own `ValueExtractor` for full control. It receives a Web-standard `Request` and returns a string or `undefined`:
+
+```ts
+app.use(
+  betterAuditExpress({
+    extractor: {
+      actor: async (request) => {
+        const apiKey = request.headers.get("x-api-key");
+        if (!apiKey) return undefined;
+        const owner = await resolveApiKeyOwner(apiKey);
+        return owner?.id;
+      },
+    },
+  }),
+);
+```
+
+## ALS scope and async handlers
+
+The middleware keeps the `AsyncLocalStorage` scope open until the response finishes (via `response.on('finish'/'close')`). This means audit context is available even after `await` inside async route handlers — the context does not reset at the first `await` boundary.
+
+## 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(
+  betterAuditExpress({
+    onError: (error) => console.error("Audit extraction failed:", error),
+  }),
+);
+```
+
+## API
+
+### `betterAuditExpress(options?)`
+
+Convenience wrapper that returns an Express middleware. Equivalent to `createExpressMiddleware`.
+
+### `createExpressMiddleware(options?)`
+
+Creates an Express-compatible middleware function `(req, res, next) => Promise<void>`.
+
+**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,86 @@
+"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, {
+  betterAuditExpress: () => betterAuditExpress,
+  createExpressMiddleware: () => createExpressMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_audit_core = require("@usebetterdev/audit-core");
+function toWebRequest(req) {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      headers.set(key, value.join(", "));
+    } else if (typeof value === "number") {
+      headers.set(key, String(value));
+    } else {
+      headers.set(key, value);
+    }
+  }
+  const rawPath = req.originalUrl ?? req.url;
+  const url = rawPath.startsWith("/") ? `http://${req.hostname ?? "localhost"}${rawPath}` : rawPath;
+  return new Request(url, {
+    method: req.method ?? "GET",
+    headers
+  });
+}
+var defaultExtractor = {
+  actor: (0, import_audit_core.fromBearerToken)("sub")
+};
+function createExpressMiddleware(options = {}) {
+  const extractor = options.extractor ?? defaultExtractor;
+  const handlerOptions = {};
+  if (options.onError) {
+    handlerOptions.onError = options.onError;
+  }
+  return async (request, response, next) => {
+    try {
+      const webRequest = toWebRequest(request);
+      const nextWrapper = () => new Promise((resolve) => {
+        const done = () => resolve();
+        if (response.on) {
+          response.on("finish", done);
+          response.on("close", done);
+        }
+        next();
+        if (!response.on) {
+          done();
+        }
+      });
+      await (0, import_audit_core.handleMiddleware)(extractor, webRequest, nextWrapper, handlerOptions);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function betterAuditExpress(options = {}) {
+  return createExpressMiddleware(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  betterAuditExpress,
+  createExpressMiddleware
+});
+//# 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\n// ---------------------------------------------------------------------------\n// Interface types\n// ---------------------------------------------------------------------------\n\nexport interface ExpressRequestLike {\n  headers: Record<string, string | string[] | number | undefined>;\n  url: string;\n  originalUrl?: string;\n  hostname?: string;\n  method?: string;\n}\n\nexport interface ExpressResponseLike {\n  /** Used to detect when the response is finished so the ALS scope stays open. Real Express responses always have this (inherited from http.ServerResponse). */\n  on?: (event: string, listener: (...args: unknown[]) => void) => unknown;\n}\n\nexport type ExpressNextFunction = (error?: unknown) => void;\n\nexport type ExpressMiddleware = (\n  request: ExpressRequestLike,\n  response: ExpressResponseLike,\n  next: ExpressNextFunction,\n) => Promise<void>;\n\nexport interface CreateExpressMiddlewareOptions {\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// ---------------------------------------------------------------------------\n// Request bridging\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge an Express `IncomingMessage`-shaped request to a Web `Request`.\n *\n * Node.js headers can be `string | string[] | number | undefined`.\n * This normalises them to the `string` values `Headers` expects:\n * - `string[]` → joined with `\", \"`\n * - `number`   → converted with `String()`\n * - `undefined`→ skipped\n *\n * **Security note:** `req.hostname` comes from the `Host` header and is\n * unvalidated user input. The reconstructed URL is used only to satisfy the\n * Web `Request` constructor — built-in extractors read headers, not the URL\n * authority. Custom extractors must not trust `new URL(request.url).hostname`.\n */\nfunction toWebRequest(req: ExpressRequestLike): Request {\n  const headers = new Headers();\n  for (const [key, value] of Object.entries(req.headers)) {\n    if (value === undefined) {\n      continue;\n    }\n    if (Array.isArray(value)) {\n      headers.set(key, value.join(\", \"));\n    } else if (typeof value === \"number\") {\n      headers.set(key, String(value));\n    } else {\n      headers.set(key, value);\n    }\n  }\n\n  const rawPath = req.originalUrl ?? req.url;\n  const url = rawPath.startsWith(\"/\")\n    ? `http://${req.hostname ?? \"localhost\"}${rawPath}`\n    : rawPath;\n\n  return new Request(url, {\n    method: req.method ?? \"GET\",\n    headers,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Default extractor\n// ---------------------------------------------------------------------------\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n// ---------------------------------------------------------------------------\n// Middleware\n// ---------------------------------------------------------------------------\n\n/**\n * Creates an Express-compatible middleware that populates audit context\n * via AsyncLocalStorage on every request.\n *\n * Bridges Express's `IncomingMessage` to a Web `Request`, then delegates\n * to the shared `handleMiddleware()` from audit-core.\n *\n * **ALS scope lifetime:** the scope stays open until the response finishes\n * (via `response.on('finish'/'close')`), so audit context is available\n * even inside `await`-ed operations in async route handlers.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds without audit context (fail open).\n */\nexport function createExpressMiddleware(\n  options: CreateExpressMiddlewareOptions = {},\n): ExpressMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const handlerOptions: MiddlewareHandlerOptions = {};\n  if (options.onError) {\n    handlerOptions.onError = options.onError;\n  }\n\n  return async (request, response, next) => {\n    try {\n      const webRequest = toWebRequest(request);\n\n      const nextWrapper = (): Promise<void> =>\n        new Promise<void>((resolve) => {\n          const done = () => resolve();\n          if (response.on) {\n            response.on(\"finish\", done);\n            response.on(\"close\", done);\n          }\n          next();\n          if (!response.on) {\n            done();\n          }\n        });\n\n      await handleMiddleware(extractor, webRequest, nextWrapper, handlerOptions);\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Convenience wrapper: `app.use(betterAuditExpress())`.\n *\n * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).\n * Pass options to customise extraction.\n */\nexport function betterAuditExpress(\n  options: CreateExpressMiddlewareOptions = {},\n): ExpressMiddleware {\n  return createExpressMiddleware(options);\n}\n\nexport type { AuditContext, ContextExtractor };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,wBAGO;AAoDP,SAAS,aAAa,KAAkC;AACtD,QAAM,UAAU,IAAI,QAAQ;AAC5B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,OAAO,GAAG;AACtD,QAAI,UAAU,QAAW;AACvB;AAAA,IACF;AACA,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,cAAQ,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,IACnC,WAAW,OAAO,UAAU,UAAU;AACpC,cAAQ,IAAI,KAAK,OAAO,KAAK,CAAC;AAAA,IAChC,OAAO;AACL,cAAQ,IAAI,KAAK,KAAK;AAAA,IACxB;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,eAAe,IAAI;AACvC,QAAM,MAAM,QAAQ,WAAW,GAAG,IAC9B,UAAU,IAAI,YAAY,WAAW,GAAG,OAAO,KAC/C;AAEJ,SAAO,IAAI,QAAQ,KAAK;AAAA,IACtB,QAAQ,IAAI,UAAU;AAAA,IACtB;AAAA,EACF,CAAC;AACH;AAOA,IAAM,mBAAqC;AAAA,EACzC,WAAO,mCAAgB,KAAK;AAC9B;AAoBO,SAAS,wBACd,UAA0C,CAAC,GACxB;AACnB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,iBAA2C,CAAC;AAClD,MAAI,QAAQ,SAAS;AACnB,mBAAe,UAAU,QAAQ;AAAA,EACnC;AAEA,SAAO,OAAO,SAAS,UAAU,SAAS;AACxC,QAAI;AACF,YAAM,aAAa,aAAa,OAAO;AAEvC,YAAM,cAAc,MAClB,IAAI,QAAc,CAAC,YAAY;AAC7B,cAAM,OAAO,MAAM,QAAQ;AAC3B,YAAI,SAAS,IAAI;AACf,mBAAS,GAAG,UAAU,IAAI;AAC1B,mBAAS,GAAG,SAAS,IAAI;AAAA,QAC3B;AACA,aAAK;AACL,YAAI,CAAC,SAAS,IAAI;AAChB,eAAK;AAAA,QACP;AAAA,MACF,CAAC;AAEH,gBAAM,oCAAiB,WAAW,YAAY,aAAa,cAAc;AAAA,IAC3E,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;AAQO,SAAS,mBACd,UAA0C,CAAC,GACxB;AACnB,SAAO,wBAAwB,OAAO;AACxC;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+import { ContextExtractor } from '@usebetterdev/audit-core';
+export { AuditContext, ContextExtractor } from '@usebetterdev/audit-core';
+
+interface ExpressRequestLike {
+    headers: Record<string, string | string[] | number | undefined>;
+    url: string;
+    originalUrl?: string;
+    hostname?: string;
+    method?: string;
+}
+interface ExpressResponseLike {
+    /** Used to detect when the response is finished so the ALS scope stays open. Real Express responses always have this (inherited from http.ServerResponse). */
+    on?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+type ExpressNextFunction = (error?: unknown) => void;
+type ExpressMiddleware = (request: ExpressRequestLike, response: ExpressResponseLike, next: ExpressNextFunction) => Promise<void>;
+interface CreateExpressMiddlewareOptions {
+    /** 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 an Express-compatible middleware that populates audit context
+ * via AsyncLocalStorage on every request.
+ *
+ * Bridges Express's `IncomingMessage` to a Web `Request`, then delegates
+ * to the shared `handleMiddleware()` from audit-core.
+ *
+ * **ALS scope lifetime:** the scope stays open until the response finishes
+ * (via `response.on('finish'/'close')`), so audit context is available
+ * even inside `await`-ed operations in async route handlers.
+ *
+ * The middleware is non-blocking: if context extraction fails, the request
+ * proceeds without audit context (fail open).
+ */
+declare function createExpressMiddleware(options?: CreateExpressMiddlewareOptions): ExpressMiddleware;
+/**
+ * Convenience wrapper: `app.use(betterAuditExpress())`.
+ *
+ * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).
+ * Pass options to customise extraction.
+ */
+declare function betterAuditExpress(options?: CreateExpressMiddlewareOptions): ExpressMiddleware;
+
+export { type CreateExpressMiddlewareOptions, type ExpressMiddleware, type ExpressNextFunction, type ExpressRequestLike, type ExpressResponseLike, betterAuditExpress, createExpressMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { ContextExtractor } from '@usebetterdev/audit-core';
+export { AuditContext, ContextExtractor } from '@usebetterdev/audit-core';
+
+interface ExpressRequestLike {
+    headers: Record<string, string | string[] | number | undefined>;
+    url: string;
+    originalUrl?: string;
+    hostname?: string;
+    method?: string;
+}
+interface ExpressResponseLike {
+    /** Used to detect when the response is finished so the ALS scope stays open. Real Express responses always have this (inherited from http.ServerResponse). */
+    on?: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+type ExpressNextFunction = (error?: unknown) => void;
+type ExpressMiddleware = (request: ExpressRequestLike, response: ExpressResponseLike, next: ExpressNextFunction) => Promise<void>;
+interface CreateExpressMiddlewareOptions {
+    /** 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 an Express-compatible middleware that populates audit context
+ * via AsyncLocalStorage on every request.
+ *
+ * Bridges Express's `IncomingMessage` to a Web `Request`, then delegates
+ * to the shared `handleMiddleware()` from audit-core.
+ *
+ * **ALS scope lifetime:** the scope stays open until the response finishes
+ * (via `response.on('finish'/'close')`), so audit context is available
+ * even inside `await`-ed operations in async route handlers.
+ *
+ * The middleware is non-blocking: if context extraction fails, the request
+ * proceeds without audit context (fail open).
+ */
+declare function createExpressMiddleware(options?: CreateExpressMiddlewareOptions): ExpressMiddleware;
+/**
+ * Convenience wrapper: `app.use(betterAuditExpress())`.
+ *
+ * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).
+ * Pass options to customise extraction.
+ */
+declare function betterAuditExpress(options?: CreateExpressMiddlewareOptions): ExpressMiddleware;
+
+export { type CreateExpressMiddlewareOptions, type ExpressMiddleware, type ExpressNextFunction, type ExpressRequestLike, type ExpressResponseLike, betterAuditExpress, createExpressMiddleware };

package/dist/index.js

@@ -0,0 +1,63 @@
+// src/index.ts
+import {
+  handleMiddleware,
+  fromBearerToken
+} from "@usebetterdev/audit-core";
+function toWebRequest(req) {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      headers.set(key, value.join(", "));
+    } else if (typeof value === "number") {
+      headers.set(key, String(value));
+    } else {
+      headers.set(key, value);
+    }
+  }
+  const rawPath = req.originalUrl ?? req.url;
+  const url = rawPath.startsWith("/") ? `http://${req.hostname ?? "localhost"}${rawPath}` : rawPath;
+  return new Request(url, {
+    method: req.method ?? "GET",
+    headers
+  });
+}
+var defaultExtractor = {
+  actor: fromBearerToken("sub")
+};
+function createExpressMiddleware(options = {}) {
+  const extractor = options.extractor ?? defaultExtractor;
+  const handlerOptions = {};
+  if (options.onError) {
+    handlerOptions.onError = options.onError;
+  }
+  return async (request, response, next) => {
+    try {
+      const webRequest = toWebRequest(request);
+      const nextWrapper = () => new Promise((resolve) => {
+        const done = () => resolve();
+        if (response.on) {
+          response.on("finish", done);
+          response.on("close", done);
+        }
+        next();
+        if (!response.on) {
+          done();
+        }
+      });
+      await handleMiddleware(extractor, webRequest, nextWrapper, handlerOptions);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+function betterAuditExpress(options = {}) {
+  return createExpressMiddleware(options);
+}
+export {
+  betterAuditExpress,
+  createExpressMiddleware
+};
+//# 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\n// ---------------------------------------------------------------------------\n// Interface types\n// ---------------------------------------------------------------------------\n\nexport interface ExpressRequestLike {\n  headers: Record<string, string | string[] | number | undefined>;\n  url: string;\n  originalUrl?: string;\n  hostname?: string;\n  method?: string;\n}\n\nexport interface ExpressResponseLike {\n  /** Used to detect when the response is finished so the ALS scope stays open. Real Express responses always have this (inherited from http.ServerResponse). */\n  on?: (event: string, listener: (...args: unknown[]) => void) => unknown;\n}\n\nexport type ExpressNextFunction = (error?: unknown) => void;\n\nexport type ExpressMiddleware = (\n  request: ExpressRequestLike,\n  response: ExpressResponseLike,\n  next: ExpressNextFunction,\n) => Promise<void>;\n\nexport interface CreateExpressMiddlewareOptions {\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// ---------------------------------------------------------------------------\n// Request bridging\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge an Express `IncomingMessage`-shaped request to a Web `Request`.\n *\n * Node.js headers can be `string | string[] | number | undefined`.\n * This normalises them to the `string` values `Headers` expects:\n * - `string[]` → joined with `\", \"`\n * - `number`   → converted with `String()`\n * - `undefined`→ skipped\n *\n * **Security note:** `req.hostname` comes from the `Host` header and is\n * unvalidated user input. The reconstructed URL is used only to satisfy the\n * Web `Request` constructor — built-in extractors read headers, not the URL\n * authority. Custom extractors must not trust `new URL(request.url).hostname`.\n */\nfunction toWebRequest(req: ExpressRequestLike): Request {\n  const headers = new Headers();\n  for (const [key, value] of Object.entries(req.headers)) {\n    if (value === undefined) {\n      continue;\n    }\n    if (Array.isArray(value)) {\n      headers.set(key, value.join(\", \"));\n    } else if (typeof value === \"number\") {\n      headers.set(key, String(value));\n    } else {\n      headers.set(key, value);\n    }\n  }\n\n  const rawPath = req.originalUrl ?? req.url;\n  const url = rawPath.startsWith(\"/\")\n    ? `http://${req.hostname ?? \"localhost\"}${rawPath}`\n    : rawPath;\n\n  return new Request(url, {\n    method: req.method ?? \"GET\",\n    headers,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Default extractor\n// ---------------------------------------------------------------------------\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n// ---------------------------------------------------------------------------\n// Middleware\n// ---------------------------------------------------------------------------\n\n/**\n * Creates an Express-compatible middleware that populates audit context\n * via AsyncLocalStorage on every request.\n *\n * Bridges Express's `IncomingMessage` to a Web `Request`, then delegates\n * to the shared `handleMiddleware()` from audit-core.\n *\n * **ALS scope lifetime:** the scope stays open until the response finishes\n * (via `response.on('finish'/'close')`), so audit context is available\n * even inside `await`-ed operations in async route handlers.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds without audit context (fail open).\n */\nexport function createExpressMiddleware(\n  options: CreateExpressMiddlewareOptions = {},\n): ExpressMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const handlerOptions: MiddlewareHandlerOptions = {};\n  if (options.onError) {\n    handlerOptions.onError = options.onError;\n  }\n\n  return async (request, response, next) => {\n    try {\n      const webRequest = toWebRequest(request);\n\n      const nextWrapper = (): Promise<void> =>\n        new Promise<void>((resolve) => {\n          const done = () => resolve();\n          if (response.on) {\n            response.on(\"finish\", done);\n            response.on(\"close\", done);\n          }\n          next();\n          if (!response.on) {\n            done();\n          }\n        });\n\n      await handleMiddleware(extractor, webRequest, nextWrapper, handlerOptions);\n    } catch (error) {\n      next(error);\n    }\n  };\n}\n\n/**\n * Convenience wrapper: `app.use(betterAuditExpress())`.\n *\n * Uses the default JWT extractor (reads `sub` from `Authorization: Bearer <jwt>`).\n * Pass options to customise extraction.\n */\nexport function betterAuditExpress(\n  options: CreateExpressMiddlewareOptions = {},\n): ExpressMiddleware {\n  return createExpressMiddleware(options);\n}\n\nexport type { AuditContext, ContextExtractor };\n"],"mappings":";AAKA;AAAA,EACE;AAAA,EACA;AAAA,OACK;AAoDP,SAAS,aAAa,KAAkC;AACtD,QAAM,UAAU,IAAI,QAAQ;AAC5B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,OAAO,GAAG;AACtD,QAAI,UAAU,QAAW;AACvB;AAAA,IACF;AACA,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,cAAQ,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC;AAAA,IACnC,WAAW,OAAO,UAAU,UAAU;AACpC,cAAQ,IAAI,KAAK,OAAO,KAAK,CAAC;AAAA,IAChC,OAAO;AACL,cAAQ,IAAI,KAAK,KAAK;AAAA,IACxB;AAAA,EACF;AAEA,QAAM,UAAU,IAAI,eAAe,IAAI;AACvC,QAAM,MAAM,QAAQ,WAAW,GAAG,IAC9B,UAAU,IAAI,YAAY,WAAW,GAAG,OAAO,KAC/C;AAEJ,SAAO,IAAI,QAAQ,KAAK;AAAA,IACtB,QAAQ,IAAI,UAAU;AAAA,IACtB;AAAA,EACF,CAAC;AACH;AAOA,IAAM,mBAAqC;AAAA,EACzC,OAAO,gBAAgB,KAAK;AAC9B;AAoBO,SAAS,wBACd,UAA0C,CAAC,GACxB;AACnB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,iBAA2C,CAAC;AAClD,MAAI,QAAQ,SAAS;AACnB,mBAAe,UAAU,QAAQ;AAAA,EACnC;AAEA,SAAO,OAAO,SAAS,UAAU,SAAS;AACxC,QAAI;AACF,YAAM,aAAa,aAAa,OAAO;AAEvC,YAAM,cAAc,MAClB,IAAI,QAAc,CAAC,YAAY;AAC7B,cAAM,OAAO,MAAM,QAAQ;AAC3B,YAAI,SAAS,IAAI;AACf,mBAAS,GAAG,UAAU,IAAI;AAC1B,mBAAS,GAAG,SAAS,IAAI;AAAA,QAC3B;AACA,aAAK;AACL,YAAI,CAAC,SAAS,IAAI;AAChB,eAAK;AAAA,QACP;AAAA,MACF,CAAC;AAEH,YAAM,iBAAiB,WAAW,YAAY,aAAa,cAAc;AAAA,IAC3E,SAAS,OAAO;AACd,WAAK,KAAK;AAAA,IACZ;AAAA,EACF;AACF;AAQO,SAAS,mBACd,UAA0C,CAAC,GACxB;AACnB,SAAO,wBAAwB,OAAO;AACxC;","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@usebetterdev/audit-express",
+  "version": "0.5.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": {
+    "express": ">=4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.0",
+    "@types/supertest": "^6.0.2",
+    "express": "^4.21.2",
+    "supertest": "^7.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2",
+    "vitest": "^2.1.6"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}