@fluyappgocore/commons-backend 1.0.211 → 1.0.213

package/build/middlewares/guestAuth.middleware.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Guest-JWT auth for the customer-facing portal.
+ *
+ * Three token levels, each signed with the shared JWT_KEY env var so
+ * every microservice (moving, video, agents) can verify them without a
+ * network round-trip:
+ *
+ *   - guest   → "I'm a visitor at entity X, branch Y" (30 min, no ticket)
+ *   - ticket  → "I'm the holder of ticket T at entity X, branch Y" (2 h)
+ *   - (livekit tokens are minted separately by livekit-server-sdk and
+ *      are NOT part of this module — they live inside msvideo)
+ *
+ * Usage in any express app:
+ *
+ *   import { verifyPortalToken, requireScope } from "@fluyappgocore/commons-backend";
+ *
+ *   router.get("/queue",
+ *     verifyPortalToken,
+ *     requireScope("guest"),  // accepts guest OR ticket
+ *     handler,
+ *   );
+ *
+ *   router.get("/tickets/:uuid",
+ *     verifyPortalToken,
+ *     requireScope("ticket"),
+ *     requireTicketMatch("uuid"),
+ *     handler,
+ *   );
+ */
+import { NextFunction, Request, Response } from "express";
+export declare type PortalScope = "guest" | "ticket";
+export interface PortalClaims {
+    /** "guest:<uuid>" or "ticket:<ticketUuid>" — useful for audit/rate-limit */
+    sub: string;
+    /** JWT audience, always "portal" so we don't cross-verify with user tokens */
+    aud: "portal";
+    scope: PortalScope;
+    entityUuid: string;
+    branchUuid: string;
+    /** Present iff scope === "ticket" */
+    ticketUuid?: string;
+    iat: number;
+    exp: number;
+}
+export interface RequestWithPortal extends Request {
+    portalAuth?: PortalClaims;
+}
+/** Issue a fresh guest token for a visitor who just landed on a branch URL. */
+export declare function issueGuestToken(input: {
+    entityUuid: string;
+    branchUuid: string;
+}): {
+    token: string;
+    expiresAt: number;
+};
+/** Upgrade a guest into a ticket holder after POST /tickets succeeds. */
+export declare function issueTicketToken(input: {
+    entityUuid: string;
+    branchUuid: string;
+    ticketUuid: string;
+}): {
+    token: string;
+    expiresAt: number;
+};
+/**
+ * Express middleware: reads `Authorization: Bearer <token>`, verifies the
+ * signature, decodes the claims, attaches them as `req.portalAuth`.
+ *
+ * Rejects anything that isn't a portal-scoped token (aud !== "portal")
+ * so a regular user/agent JWT can NEVER accidentally pass this gate.
+ */
+export declare function verifyPortalToken(req: RequestWithPortal, _res: Response, next: NextFunction): void;
+/**
+ * Gate a route by scope.
+ *
+ * `requireScope("guest")` accepts BOTH guest and ticket tokens (ticket
+ * implies guest, since a ticket holder is also a visitor at that branch).
+ *
+ * `requireScope("ticket")` accepts only ticket tokens.
+ */
+export declare function requireScope(minimum: PortalScope): (req: RequestWithPortal, _res: Response, next: NextFunction) => void;
+/**
+ * Guard that the `ticketUuid` claim inside the JWT matches the URL param.
+ * Prevents a ticket holder from reading someone else's ticket by tampering
+ * with the path.
+ */
+export declare function requireTicketMatch(paramName?: string): (req: RequestWithPortal, _res: Response, next: NextFunction) => void;
+/**
+ * Guard that the `branchUuid` claim inside the JWT matches the URL param
+ * or body field. Same idea, one layer up.
+ */
+export declare function requireBranchMatch(source: "params" | "body", fieldName: string): (req: RequestWithPortal, _res: Response, next: NextFunction) => void;

package/build/middlewares/guestAuth.middleware.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireBranchMatch = exports.requireTicketMatch = exports.requireScope = exports.verifyPortalToken = exports.issueTicketToken = exports.issueGuestToken = void 0;
+var jwt = __importStar(require("jsonwebtoken"));
+var exceptions_1 = require("../exceptions");
+var SECRET = process.env.JWT_KEY || "";
+var GUEST_TTL_SEC = 30 * 60; // 30 minutes
+var TICKET_TTL_SEC = 2 * 60 * 60; // 2 hours
+function randomId() {
+    return (Date.now().toString(36) +
+        Math.random().toString(36).slice(2, 10));
+}
+/** Issue a fresh guest token for a visitor who just landed on a branch URL. */
+function issueGuestToken(input) {
+    var now = Math.floor(Date.now() / 1000);
+    var exp = now + GUEST_TTL_SEC;
+    var payload = {
+        sub: "guest:" + randomId(),
+        aud: "portal",
+        scope: "guest",
+        entityUuid: input.entityUuid,
+        branchUuid: input.branchUuid,
+        iat: now,
+        exp: exp,
+    };
+    var token = jwt.sign(payload, SECRET, { algorithm: "HS256" });
+    return { token: token, expiresAt: exp * 1000 };
+}
+exports.issueGuestToken = issueGuestToken;
+/** Upgrade a guest into a ticket holder after POST /tickets succeeds. */
+function issueTicketToken(input) {
+    var now = Math.floor(Date.now() / 1000);
+    var exp = now + TICKET_TTL_SEC;
+    var payload = {
+        sub: "ticket:" + input.ticketUuid,
+        aud: "portal",
+        scope: "ticket",
+        entityUuid: input.entityUuid,
+        branchUuid: input.branchUuid,
+        ticketUuid: input.ticketUuid,
+        iat: now,
+        exp: exp,
+    };
+    var token = jwt.sign(payload, SECRET, { algorithm: "HS256" });
+    return { token: token, expiresAt: exp * 1000 };
+}
+exports.issueTicketToken = issueTicketToken;
+/**
+ * Express middleware: reads `Authorization: Bearer <token>`, verifies the
+ * signature, decodes the claims, attaches them as `req.portalAuth`.
+ *
+ * Rejects anything that isn't a portal-scoped token (aud !== "portal")
+ * so a regular user/agent JWT can NEVER accidentally pass this gate.
+ */
+function verifyPortalToken(req, _res, next) {
+    var _a;
+    var auth = (_a = req.headers) === null || _a === void 0 ? void 0 : _a.authorization;
+    if (!auth || !auth.startsWith("Bearer ")) {
+        return next(new exceptions_1.HttpException(401, "Missing portal token"));
+    }
+    var token = auth.slice("Bearer ".length).trim();
+    try {
+        var decoded = jwt.verify(token, SECRET, {
+            algorithms: ["HS256"],
+        });
+        if (decoded.aud !== "portal") {
+            return next(new exceptions_1.HttpException(401, "Invalid token audience"));
+        }
+        req.portalAuth = decoded;
+        return next();
+    }
+    catch (err) {
+        return next(new exceptions_1.HttpException(401, (err === null || err === void 0 ? void 0 : err.name) === "TokenExpiredError"
+            ? "Portal token expired"
+            : "Invalid portal token"));
+    }
+}
+exports.verifyPortalToken = verifyPortalToken;
+/**
+ * Gate a route by scope.
+ *
+ * `requireScope("guest")` accepts BOTH guest and ticket tokens (ticket
+ * implies guest, since a ticket holder is also a visitor at that branch).
+ *
+ * `requireScope("ticket")` accepts only ticket tokens.
+ */
+function requireScope(minimum) {
+    return function (req, _res, next) {
+        if (!req.portalAuth) {
+            return next(new exceptions_1.HttpException(401, "Portal token not verified"));
+        }
+        if (minimum === "ticket" && req.portalAuth.scope !== "ticket") {
+            return next(new exceptions_1.HttpException(403, "Ticket-scoped token required"));
+        }
+        return next();
+    };
+}
+exports.requireScope = requireScope;
+/**
+ * Guard that the `ticketUuid` claim inside the JWT matches the URL param.
+ * Prevents a ticket holder from reading someone else's ticket by tampering
+ * with the path.
+ */
+function requireTicketMatch(paramName) {
+    if (paramName === void 0) { paramName = "uuid"; }
+    return function (req, _res, next) {
+        var _a, _b;
+        var claimed = (_a = req.portalAuth) === null || _a === void 0 ? void 0 : _a.ticketUuid;
+        var requested = (_b = req.params) === null || _b === void 0 ? void 0 : _b[paramName];
+        if (!claimed || !requested || claimed !== requested) {
+            return next(new exceptions_1.HttpException(403, "Ticket id mismatch"));
+        }
+        return next();
+    };
+}
+exports.requireTicketMatch = requireTicketMatch;
+/**
+ * Guard that the `branchUuid` claim inside the JWT matches the URL param
+ * or body field. Same idea, one layer up.
+ */
+function requireBranchMatch(source, fieldName) {
+    return function (req, _res, next) {
+        var _a, _b, _c;
+        var claimed = (_a = req.portalAuth) === null || _a === void 0 ? void 0 : _a.branchUuid;
+        var requested = source === "params" ? (_b = req.params) === null || _b === void 0 ? void 0 : _b[fieldName] : (_c = req.body) === null || _c === void 0 ? void 0 : _c[fieldName];
+        if (!claimed || !requested || claimed !== requested) {
+            return next(new exceptions_1.HttpException(403, "Branch id mismatch"));
+        }
+        return next();
+    };
+}
+exports.requireBranchMatch = requireBranchMatch;

package/build/middlewares/index.d.ts

@@ -2,3 +2,4 @@ export * from './auth.middleware';
 export * from './error.middleware';
 export * from './validation.middleware';
 export * from './licenseGuard.middleware';
+export * from './guestAuth.middleware';

package/build/middlewares/index.js

@@ -14,3 +14,4 @@ __exportStar(require("./auth.middleware"), exports);
 __exportStar(require("./error.middleware"), exports);
 __exportStar(require("./validation.middleware"), exports);
 __exportStar(require("./licenseGuard.middleware"), exports);
+__exportStar(require("./guestAuth.middleware"), exports);

package/build/middlewares/licenseGuard.middleware.js

@@ -39,42 +39,87 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLicenseStatus = exports.licenseLoginGuard = exports.licenseWriteGuard = exports.licenseGuard = exports.getLicenseLimits = exports.isLicenseFeatureEnabled = void 0;
 var cache = null;
 var CACHE_TTL = 1000 * 60 * 60; // 1 hour
+/**
+ * Where to fetch license data from. Two modes:
+ *
+ *   - LICENSE_PROXY_URL set → in-cluster proxy (recommended).
+ *     All MS except ms-entity hit `${LICENSE_PROXY_URL}` which resolves to
+ *     `http://msentities-clusterip-srv:8092/api_entities/internal/license-status`.
+ *     Only ms-entity itself actually talks to licensing.fluyapp.io. Dramatic
+ *     reduction in outbound traffic (N × M → 1 × M).
+ *
+ *   - LICENSE_URL set → direct fetch from the licensing server.
+ *     Used by ms-entity (which IS the aggregator) and as fallback for any MS
+ *     where the proxy is unreachable.
+ *
+ * If both are set, the proxy is tried first; on failure we fall back to the
+ * direct URL so a network issue between MS doesn't break licensing for
+ * everyone.
+ */
 function fetchLicense() {
     return __awaiter(this, void 0, void 0, function () {
-        var licenseUrl, installationUuid, controller_1, timeout_1, res, data, _a;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        function tryFetch(url, isProxy) {
+            return __awaiter(this, void 0, void 0, function () {
+                var controller_1, timeout_1, headers, res, data, _a;
+                return __generator(this, function (_b) {
+                    switch (_b.label) {
+                        case 0:
+                            _b.trys.push([0, 3, , 4]);
+                            controller_1 = new AbortController();
+                            timeout_1 = setTimeout(function () { return controller_1.abort(); }, 5000);
+                            headers = {};
+                            if (isProxy && internalSecret)
+                                headers["x-internal-secret"] = internalSecret;
+                            return [4 /*yield*/, fetch(url, { signal: controller_1.signal, headers: headers })
+                                    .finally(function () { return clearTimeout(timeout_1); })];
+                        case 1:
+                            res = _b.sent();
+                            if (!res.ok)
+                                return [2 /*return*/, null];
+                            return [4 /*yield*/, res.json()];
+                        case 2:
+                            data = _b.sent();
+                            return [2 /*return*/, {
+                                    valid: data.valid,
+                                    readOnly: data.readOnly || false,
+                                    blocked: data.blocked || false,
+                                    features: data.features || {},
+                                    limits: data.limits || {},
+                                    tier: data.tier || "BASIC",
+                                    fetchedAt: Date.now(),
+                                }];
+                        case 3:
+                            _a = _b.sent();
+                            return [2 /*return*/, null];
+                        case 4: return [2 /*return*/];
+                    }
+                });
+            });
+        }
+        var proxyUrl, licenseUrl, installationUuid, internalSecret, cached, cached;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
                 case 0:
+                    proxyUrl = process.env.LICENSE_PROXY_URL || "";
                     licenseUrl = process.env.LICENSE_URL || "";
                     installationUuid = process.env.INSTALLATION_UUID || process.env.ENTITY_UUID || "";
-                    if (!licenseUrl || !installationUuid)
-                        return [2 /*return*/, null];
-                    _b.label = 1;
+                    internalSecret = process.env.INTERNAL_SECRET || "";
+                    if (!proxyUrl) return [3 /*break*/, 2];
+                    return [4 /*yield*/, tryFetch(proxyUrl, true)];
                 case 1:
-                    _b.trys.push([1, 4, , 5]);
-                    controller_1 = new AbortController();
-                    timeout_1 = setTimeout(function () { return controller_1.abort(); }, 5000);
-                    return [4 /*yield*/, fetch(licenseUrl + "/api/license/validate/" + installationUuid, { signal: controller_1.signal }).finally(function () { return clearTimeout(timeout_1); })];
+                    cached = _a.sent();
+                    if (cached)
+                        return [2 /*return*/, cached];
+                    _a.label = 2;
                 case 2:
-                    res = _b.sent();
-                    if (!res.ok)
-                        return [2 /*return*/, null];
-                    return [4 /*yield*/, res.json()];
+                    if (!(licenseUrl && installationUuid)) return [3 /*break*/, 4];
+                    return [4 /*yield*/, tryFetch(licenseUrl + "/api/license/validate/" + installationUuid, false)];
                 case 3:
-                    data = _b.sent();
-                    return [2 /*return*/, {
-                            valid: data.valid,
-                            readOnly: data.readOnly || false,
-                            blocked: data.blocked || false,
-                            features: data.features || {},
-                            limits: data.limits || {},
-                            tier: data.tier || "BASIC",
-                            fetchedAt: Date.now(),
-                        }];
-                case 4:
-                    _a = _b.sent();
-                    return [2 /*return*/, null];
-                case 5: return [2 /*return*/];
+                    cached = _a.sent();
+                    if (cached)
+                        return [2 /*return*/, cached];
+                    _a.label = 4;
+                case 4: return [2 /*return*/, null];
             }
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluyappgocore/commons-backend",
-  "version": "1.0.211",
+  "version": "1.0.213",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",