@webpieces/http-server 0.4.880 → 0.4.881

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-server",
-  "version": "0.4.880",
+  "version": "0.4.881",
   "description": "WebPieces server with filter chain and dependency injection",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,10 +22,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-context": "0.4.880",
-    "@webpieces/core-util": "0.4.880",
-    "@webpieces/gcp-identity": "0.4.880",
-    "@webpieces/http-routing": "0.4.880",
+    "@webpieces/core-context": "0.4.881",
+    "@webpieces/core-util": "0.4.881",
+    "@webpieces/gcp-identity": "0.4.881",
+    "@webpieces/http-routing": "0.4.881",
     "cors": "2.8.5",
     "express": "5.1.0",
     "inversify": "7.10.4"

package/src/OAuthExpressErrorHandler.d.ts

@@ -0,0 +1,32 @@
+import { NextFunction, Request, Response } from 'express';
+import { OAuthProtocolError } from '@webpieces/core-util';
+/**
+ * The express boundary for an app's OWN OAuth routes — `/oauth/token`, `/oauth/register`,
+ * `/oauth/authorize` — which an app mounts directly on express beside `WpMcpServer.bind(...)`
+ * (webpieces leaves token issuance pluggable). It answers an {@link OAuthProtocolError} in the RFC
+ * 6749/6750 shape and logs it at INFO as an EXPECTED refusal (#1176); anything else is passed to
+ * the next express error handler untouched, so a real bug is still a fault.
+ *
+ * Two ways to use it, for the two shapes a raw route boundary takes:
+ *
+ * ```ts
+ * const oauthErrors = new OAuthExpressErrorHandler();
+ * // 1. as express error middleware (express 5 forwards an async handler's rejection to it)
+ * app.post('/oauth/token', urlencoded({ extended: false }), tokenHandler, oauthErrors.middleware);
+ * // 2. from a route's own try/catch
+ * if (err instanceof OAuthProtocolError) oauthErrors.write(res, err);
+ * ```
+ *
+ * A webpieces `@Endpoint` that throws an `OAuthProtocolError` needs neither: the default
+ * `ErrorTranslator` renders it with the same `OAuthErrorResponse`.
+ */
+export declare class OAuthExpressErrorHandler {
+    private readonly responseWriter;
+    /**
+     * Express error middleware (four parameters, which is how express recognises one). An arrow
+     * property so it can be handed to `app.use(...)` without losing `this`.
+     */
+    readonly middleware: (failure: unknown, _req: Request, res: Response, next: NextFunction) => void;
+    /** Write `error` in the RFC shape, with its status and headers, and log it at INFO. */
+    write(res: Response, error: OAuthProtocolError): void;
+}

package/src/OAuthExpressErrorHandler.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthExpressErrorHandler = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const ExpressResponseWriter_1 = require("./ExpressResponseWriter");
+const log = core_util_1.LogManager.getLogger('OAuthExpressErrorHandler');
+/**
+ * The express boundary for an app's OWN OAuth routes — `/oauth/token`, `/oauth/register`,
+ * `/oauth/authorize` — which an app mounts directly on express beside `WpMcpServer.bind(...)`
+ * (webpieces leaves token issuance pluggable). It answers an {@link OAuthProtocolError} in the RFC
+ * 6749/6750 shape and logs it at INFO as an EXPECTED refusal (#1176); anything else is passed to
+ * the next express error handler untouched, so a real bug is still a fault.
+ *
+ * Two ways to use it, for the two shapes a raw route boundary takes:
+ *
+ * ```ts
+ * const oauthErrors = new OAuthExpressErrorHandler();
+ * // 1. as express error middleware (express 5 forwards an async handler's rejection to it)
+ * app.post('/oauth/token', urlencoded({ extended: false }), tokenHandler, oauthErrors.middleware);
+ * // 2. from a route's own try/catch
+ * if (err instanceof OAuthProtocolError) oauthErrors.write(res, err);
+ * ```
+ *
+ * A webpieces `@Endpoint` that throws an `OAuthProtocolError` needs neither: the default
+ * `ErrorTranslator` renders it with the same `OAuthErrorResponse`.
+ */
+class OAuthExpressErrorHandler {
+    responseWriter = new ExpressResponseWriter_1.ExpressResponseWriter();
+    /**
+     * Express error middleware (four parameters, which is how express recognises one). An arrow
+     * property so it can be handed to `app.use(...)` without losing `this`.
+     */
+    // webpieces-disable no-any-unknown -- express hands an error handler whatever was thrown
+    middleware = (failure, _req, res, next) => {
+        if (!(failure instanceof core_util_1.OAuthProtocolError)) {
+            next(failure);
+            return;
+        }
+        this.write(res, failure);
+    };
+    /** Write `error` in the RFC shape, with its status and headers, and log it at INFO. */
+    write(res, error) {
+        const level = error.isCallerError() ? 'refused' : 'unavailable';
+        log.info(`OAuth request ${level}: status=${error.status} error=${error.error} message=${error.message}`);
+        if (res.headersSent) {
+            res.end();
+            return;
+        }
+        this.responseWriter.write(res, core_util_1.OAuthErrorResponse.toResponse(error, undefined));
+    }
+}
+exports.OAuthExpressErrorHandler = OAuthExpressErrorHandler;
+//# sourceMappingURL=OAuthExpressErrorHandler.js.map

package/src/OAuthExpressErrorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthExpressErrorHandler.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/OAuthExpressErrorHandler.ts"],"names":[],"mappings":";;;AACA,oDAA0F;AAC1F,mEAAgE;AAEhE,MAAM,GAAG,GAAG,sBAAU,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,wBAAwB;IAChB,cAAc,GAAG,IAAI,6CAAqB,EAAE,CAAC;IAE9D;;;OAGG;IACH,yFAAyF;IAChF,UAAU,GAAG,CAClB,OAAgB,EAChB,IAAa,EACb,GAAa,EACb,IAAkB,EACd,EAAE;QACN,IAAI,CAAC,CAAC,OAAO,YAAY,8BAAkB,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,OAAO,CAAC,CAAC;YACd,OAAO;QACX,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC,CAAC;IAEF,uFAAuF;IACvF,KAAK,CAAC,GAAa,EAAE,KAAyB;QAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC;QAChE,GAAG,CAAC,IAAI,CACJ,iBAAiB,KAAK,YAAY,KAAK,CAAC,MAAM,UAAU,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,OAAO,EAAE,CACjG,CAAC;QACF,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;YAClB,GAAG,CAAC,GAAG,EAAE,CAAC;YACV,OAAO;QACX,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,8BAAkB,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IACpF,CAAC;CACJ;AAjCD,4DAiCC","sourcesContent":["import { NextFunction, Request, Response } from 'express';\nimport { LogManager, OAuthErrorResponse, OAuthProtocolError } from '@webpieces/core-util';\nimport { ExpressResponseWriter } from './ExpressResponseWriter';\n\nconst log = LogManager.getLogger('OAuthExpressErrorHandler');\n\n/**\n * The express boundary for an app's OWN OAuth routes — `/oauth/token`, `/oauth/register`,\n * `/oauth/authorize` — which an app mounts directly on express beside `WpMcpServer.bind(...)`\n * (webpieces leaves token issuance pluggable). It answers an {@link OAuthProtocolError} in the RFC\n * 6749/6750 shape and logs it at INFO as an EXPECTED refusal (#1176); anything else is passed to\n * the next express error handler untouched, so a real bug is still a fault.\n *\n * Two ways to use it, for the two shapes a raw route boundary takes:\n *\n * ```ts\n * const oauthErrors = new OAuthExpressErrorHandler();\n * // 1. as express error middleware (express 5 forwards an async handler's rejection to it)\n * app.post('/oauth/token', urlencoded({ extended: false }), tokenHandler, oauthErrors.middleware);\n * // 2. from a route's own try/catch\n * if (err instanceof OAuthProtocolError) oauthErrors.write(res, err);\n * ```\n *\n * A webpieces `@Endpoint` that throws an `OAuthProtocolError` needs neither: the default\n * `ErrorTranslator` renders it with the same `OAuthErrorResponse`.\n */\nexport class OAuthExpressErrorHandler {\n    private readonly responseWriter = new ExpressResponseWriter();\n\n    /**\n     * Express error middleware (four parameters, which is how express recognises one). An arrow\n     * property so it can be handed to `app.use(...)` without losing `this`.\n     */\n    // webpieces-disable no-any-unknown -- express hands an error handler whatever was thrown\n    readonly middleware = (\n        failure: unknown,\n        _req: Request,\n        res: Response,\n        next: NextFunction,\n    ): void => {\n        if (!(failure instanceof OAuthProtocolError)) {\n            next(failure);\n            return;\n        }\n        this.write(res, failure);\n    };\n\n    /** Write `error` in the RFC shape, with its status and headers, and log it at INFO. */\n    write(res: Response, error: OAuthProtocolError): void {\n        const level = error.isCallerError() ? 'refused' : 'unavailable';\n        log.info(\n            `OAuth request ${level}: status=${error.status} error=${error.error} message=${error.message}`,\n        );\n        if (res.headersSent) {\n            res.end();\n            return;\n        }\n        this.responseWriter.write(res, OAuthErrorResponse.toResponse(error, undefined));\n    }\n}\n"]}

package/src/index.d.ts

@@ -5,6 +5,7 @@ export { StreamBodyReader } from './body/StreamBodyReader';
 export { PreConsumedBodyReader } from './body/PreConsumedBodyReader';
 export { RecordingFilter } from './filters/RecordingFilter';
 export { ExpressResponseWriter } from './ExpressResponseWriter';
+export { OAuthExpressErrorHandler } from './OAuthExpressErrorHandler';
 export { TestCaseRecorderImpl } from './recorder/TestCaseRecorderImpl';
 export { SpecGenerator } from './recorder/SpecGenerator';
 export { recordable } from './recorder/recordable';

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SharedSecrets = exports.AuthenticatedCaller = exports.AuthConfig = exports.HttpRequest = exports.ApiClient = exports.FilterDefinition = exports.FilterMatcher = exports.MethodMeta = exports.RouteHandler = exports.HeaderRegistry = exports.WebpiecesCoreHeaders = exports.recordable = exports.SpecGenerator = exports.TestCaseRecorderImpl = exports.ExpressResponseWriter = exports.RecordingFilter = exports.PreConsumedBodyReader = exports.StreamBodyReader = exports.WebpiecesMiddleware = exports.WebpiecesExpressRouter = void 0;
+exports.SharedSecrets = exports.AuthenticatedCaller = exports.AuthConfig = exports.HttpRequest = exports.ApiClient = exports.FilterDefinition = exports.FilterMatcher = exports.MethodMeta = exports.RouteHandler = exports.HeaderRegistry = exports.WebpiecesCoreHeaders = exports.recordable = exports.SpecGenerator = exports.TestCaseRecorderImpl = exports.OAuthExpressErrorHandler = exports.ExpressResponseWriter = exports.RecordingFilter = exports.PreConsumedBodyReader = exports.StreamBodyReader = exports.WebpiecesMiddleware = exports.WebpiecesExpressRouter = void 0;
 // Express adapter (the only place express lifecycle lives) over the node-only ApiFactory
 var WebpiecesExpressRouter_1 = require("./WebpiecesExpressRouter");
 Object.defineProperty(exports, "WebpiecesExpressRouter", { enumerable: true, get: function () { return WebpiecesExpressRouter_1.WebpiecesExpressRouter; } });
@@ -20,6 +20,9 @@ Object.defineProperty(exports, "RecordingFilter", { enumerable: true, get: funct
 // plus one header") rather than copying its status-to-message table.
 var ExpressResponseWriter_1 = require("./ExpressResponseWriter");
 Object.defineProperty(exports, "ExpressResponseWriter", { enumerable: true, get: function () { return ExpressResponseWriter_1.ExpressResponseWriter; } });
+// RFC 6749/6750 rendering + INFO logging of an OAuthProtocolError on an app's raw express OAuth routes.
+var OAuthExpressErrorHandler_1 = require("./OAuthExpressErrorHandler");
+Object.defineProperty(exports, "OAuthExpressErrorHandler", { enumerable: true, get: function () { return OAuthExpressErrorHandler_1.OAuthExpressErrorHandler; } });
 // How ApiEndUserError is answered: 'gui' (266, default) or 'edge' (its edgeHttpStatus, else 400).
 // Test-case recording (contract lives in @webpieces/core-util)
 var TestCaseRecorderImpl_1 = require("./recorder/TestCaseRecorderImpl");

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/index.ts"],"names":[],"mappings":";;;AAAA,yFAAyF;AACzF,mEAAkE;AAAzD,gIAAA,sBAAsB,OAAA;AAC/B,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAI5B,4DAA2D;AAAlD,oHAAA,gBAAgB,OAAA;AACzB,sEAAqE;AAA5D,8HAAA,qBAAqB,OAAA;AAC9B,gGAAgG;AAChG,+FAA+F;AAC/F,+FAA+F;AAC/F,6DAA4D;AAAnD,kHAAA,eAAe,OAAA;AAExB,4FAA4F;AAC5F,mGAAmG;AACnG,qEAAqE;AACrE,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,kGAAkG;AAElG,+DAA+D;AAC/D,wEAAuE;AAA9D,4HAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,8GAAA,aAAa,OAAA;AACtB,oDAAmD;AAA1C,wGAAA,UAAU,OAAA;AAEnB,mEAAmE;AACnE,uEAAsE;AAA7D,4HAAA,oBAAoB,OAAA;AAC7B,kDAAsD;AAA7C,2GAAA,cAAc,OAAA;AAEvB,gEAAgE;AAChE,wDAYiC;AAX7B,4GAAA,YAAY,OAAA;AACZ,0GAAA,UAAU,OAAA;AAEV,6GAAA,aAAa,OAAA;AACb,gHAAA,gBAAgB,OAAA;AAEhB,yGAAA,SAAS,OAAA;AACT,2GAAA,WAAW,OAAA;AACX,0GAAA,UAAU,OAAA;AACV,mHAAA,mBAAmB,OAAA;AACnB,6GAAA,aAAa,OAAA","sourcesContent":["// Express adapter (the only place express lifecycle lives) over the node-only ApiFactory\nexport { WebpiecesExpressRouter } from './WebpiecesExpressRouter';\nexport { WebpiecesMiddleware } from './WebpiecesMiddleware';\n// How routes read the body bytes: stream (default) or a host's pre-consumed req.rawBody (issue #937).\n// Chosen via WebpiecesExpressRouter.setBodyReader(...) before bindExpress(app).\nexport { RequestBodyReader } from './body/RequestBodyReader';\nexport { StreamBodyReader } from './body/StreamBodyReader';\nexport { PreConsumedBodyReader } from './body/PreConsumedBodyReader';\n// LogApiFilter is now a FIXED framework filter auto-installed by WebpiecesRouter (outermost, at\n// priority 1,000,000, above AuthFilter). Apps must NOT install it themselves — it is no longer\n// exported here. Remove any `router.addFilter(new FilterDefinition(1800, LogApiFilter, '*'))`.\nexport { RecordingFilter } from './filters/RecordingFilter';\n\n// The webpieces DEFAULT error response, exported as a DELEGABLE object: it returns the same\n// HttpResponseDto an app's ErrorTranslator.toWire returns, so an app wraps it (\"webpieces' answer,\n// plus one header\") rather than copying its status-to-message table.\nexport { ExpressResponseWriter } from './ExpressResponseWriter';\n// How ApiEndUserError is answered: 'gui' (266, default) or 'edge' (its edgeHttpStatus, else 400).\n\n// Test-case recording (contract lives in @webpieces/core-util)\nexport { TestCaseRecorderImpl } from './recorder/TestCaseRecorderImpl';\nexport { SpecGenerator } from './recorder/SpecGenerator';\nexport { recordable } from './recorder/recordable';\n\n// Context keys + registry (the global magic-context header system)\nexport { WebpiecesCoreHeaders } from './headers/WebpiecesCoreHeaders';\nexport { HeaderRegistry } from '@webpieces/core-util';\n\n// Re-export from http-routing for one-import adapter ergonomics\nexport {\n    RouteHandler,\n    MethodMeta,\n    HttpFilter,\n    FilterMatcher,\n    FilterDefinition,\n    ApiFactory,\n    ApiClient,\n    HttpRequest,\n    AuthConfig,\n    AuthenticatedCaller,\n    SharedSecrets,\n} from '@webpieces/http-routing';\n// ExpressRouteHandler now lives in http-server (express adapter), not node-only http-routing\nexport { ExpressRouteHandler } from './WebpiecesMiddleware';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/index.ts"],"names":[],"mappings":";;;AAAA,yFAAyF;AACzF,mEAAkE;AAAzD,gIAAA,sBAAsB,OAAA;AAC/B,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAI5B,4DAA2D;AAAlD,oHAAA,gBAAgB,OAAA;AACzB,sEAAqE;AAA5D,8HAAA,qBAAqB,OAAA;AAC9B,gGAAgG;AAChG,+FAA+F;AAC/F,+FAA+F;AAC/F,6DAA4D;AAAnD,kHAAA,eAAe,OAAA;AAExB,4FAA4F;AAC5F,mGAAmG;AACnG,qEAAqE;AACrE,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,wGAAwG;AACxG,uEAAsE;AAA7D,oIAAA,wBAAwB,OAAA;AACjC,kGAAkG;AAElG,+DAA+D;AAC/D,wEAAuE;AAA9D,4HAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,8GAAA,aAAa,OAAA;AACtB,oDAAmD;AAA1C,wGAAA,UAAU,OAAA;AAEnB,mEAAmE;AACnE,uEAAsE;AAA7D,4HAAA,oBAAoB,OAAA;AAC7B,kDAAsD;AAA7C,2GAAA,cAAc,OAAA;AAEvB,gEAAgE;AAChE,wDAYiC;AAX7B,4GAAA,YAAY,OAAA;AACZ,0GAAA,UAAU,OAAA;AAEV,6GAAA,aAAa,OAAA;AACb,gHAAA,gBAAgB,OAAA;AAEhB,yGAAA,SAAS,OAAA;AACT,2GAAA,WAAW,OAAA;AACX,0GAAA,UAAU,OAAA;AACV,mHAAA,mBAAmB,OAAA;AACnB,6GAAA,aAAa,OAAA","sourcesContent":["// Express adapter (the only place express lifecycle lives) over the node-only ApiFactory\nexport { WebpiecesExpressRouter } from './WebpiecesExpressRouter';\nexport { WebpiecesMiddleware } from './WebpiecesMiddleware';\n// How routes read the body bytes: stream (default) or a host's pre-consumed req.rawBody (issue #937).\n// Chosen via WebpiecesExpressRouter.setBodyReader(...) before bindExpress(app).\nexport { RequestBodyReader } from './body/RequestBodyReader';\nexport { StreamBodyReader } from './body/StreamBodyReader';\nexport { PreConsumedBodyReader } from './body/PreConsumedBodyReader';\n// LogApiFilter is now a FIXED framework filter auto-installed by WebpiecesRouter (outermost, at\n// priority 1,000,000, above AuthFilter). Apps must NOT install it themselves — it is no longer\n// exported here. Remove any `router.addFilter(new FilterDefinition(1800, LogApiFilter, '*'))`.\nexport { RecordingFilter } from './filters/RecordingFilter';\n\n// The webpieces DEFAULT error response, exported as a DELEGABLE object: it returns the same\n// HttpResponseDto an app's ErrorTranslator.toWire returns, so an app wraps it (\"webpieces' answer,\n// plus one header\") rather than copying its status-to-message table.\nexport { ExpressResponseWriter } from './ExpressResponseWriter';\n// RFC 6749/6750 rendering + INFO logging of an OAuthProtocolError on an app's raw express OAuth routes.\nexport { OAuthExpressErrorHandler } from './OAuthExpressErrorHandler';\n// How ApiEndUserError is answered: 'gui' (266, default) or 'edge' (its edgeHttpStatus, else 400).\n\n// Test-case recording (contract lives in @webpieces/core-util)\nexport { TestCaseRecorderImpl } from './recorder/TestCaseRecorderImpl';\nexport { SpecGenerator } from './recorder/SpecGenerator';\nexport { recordable } from './recorder/recordable';\n\n// Context keys + registry (the global magic-context header system)\nexport { WebpiecesCoreHeaders } from './headers/WebpiecesCoreHeaders';\nexport { HeaderRegistry } from '@webpieces/core-util';\n\n// Re-export from http-routing for one-import adapter ergonomics\nexport {\n    RouteHandler,\n    MethodMeta,\n    HttpFilter,\n    FilterMatcher,\n    FilterDefinition,\n    ApiFactory,\n    ApiClient,\n    HttpRequest,\n    AuthConfig,\n    AuthenticatedCaller,\n    SharedSecrets,\n} from '@webpieces/http-routing';\n// ExpressRouteHandler now lives in http-server (express adapter), not node-only http-routing\nexport { ExpressRouteHandler } from './WebpiecesMiddleware';\n"]}