@tumbaland/backend-core 1.24.0 → 1.26.0

package/dist/groups/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/groups/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrF,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/groups/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupOwnerSubject = exports.clearGroupOwnerCache = exports.invalidateGroupOwner = exports.getGroupOwner = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "getGroupOwner", { enumerable: true, get: function () { return client_1.getGroupOwner; } });
+Object.defineProperty(exports, "invalidateGroupOwner", { enumerable: true, get: function () { return client_1.invalidateGroupOwner; } });
+Object.defineProperty(exports, "clearGroupOwnerCache", { enumerable: true, get: function () { return client_1.clearGroupOwnerCache; } });
+var subject_1 = require("./subject");
+Object.defineProperty(exports, "groupOwnerSubject", { enumerable: true, get: function () { return subject_1.groupOwnerSubject; } });
+//# sourceMappingURL=index.js.map

package/dist/groups/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/groups/index.ts"],"names":[],"mappings":";;;AAAA,mCAAqF;AAA5E,uGAAA,aAAa,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAGlE,qCAA8C;AAArC,4GAAA,iBAAiB,OAAA"}

package/dist/groups/subject.d.ts

@@ -0,0 +1,30 @@
+import { Request } from 'express';
+import { SubjectResolver } from '../entitlements/middleware';
+export type GroupIdResolver = (req: Request) => string | undefined | Promise<string | undefined>;
+/**
+ * Builds the `subject` resolver that `requireQuota` / `requireEntitlement`
+ * already accept, for the meters whose resource can live in a group.
+ *
+ * ```ts
+ * requireQuota('storageBytes', {
+ *   subject: groupOwnerSubject(req => req.body.groupId),
+ *   amount: req => req.body.sizeBytes
+ * })
+ * ```
+ *
+ * Personal rows keep billing to the caller; group rows bill to the group's
+ * owner, because Family sells *pooled* storage and seats and the uploader's own
+ * free tier is not the pool.
+ *
+ * **When the owner cannot be resolved, it bills the caller and says so.** The
+ * alternative — refusing the write — is harsher than what the entitlement
+ * client itself does for the same class of outage (it degrades to free limits
+ * rather than denying), and the error direction here is bounded in the shape
+ * that matters: the common case is a member on a cheap personal plan uploading
+ * into a group owned by someone on Family, so falling back to the caller checks
+ * against the *smaller* allowance. It can over-grant when the caller happens to
+ * hold the richer plan, which is why it logs at `error` — a run of these means
+ * group-service is down, not that a limit is wrong.
+ */
+export declare function groupOwnerSubject(resolveGroupId: GroupIdResolver): SubjectResolver;
+//# sourceMappingURL=subject.d.ts.map

package/dist/groups/subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/groups/subject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,eAAe,GAAG,eAAe,CAiBlF"}

package/dist/groups/subject.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupOwnerSubject = groupOwnerSubject;
+const logger_1 = __importDefault(require("../logging/logger"));
+const client_1 = require("./client");
+/**
+ * Builds the `subject` resolver that `requireQuota` / `requireEntitlement`
+ * already accept, for the meters whose resource can live in a group.
+ *
+ * ```ts
+ * requireQuota('storageBytes', {
+ *   subject: groupOwnerSubject(req => req.body.groupId),
+ *   amount: req => req.body.sizeBytes
+ * })
+ * ```
+ *
+ * Personal rows keep billing to the caller; group rows bill to the group's
+ * owner, because Family sells *pooled* storage and seats and the uploader's own
+ * free tier is not the pool.
+ *
+ * **When the owner cannot be resolved, it bills the caller and says so.** The
+ * alternative — refusing the write — is harsher than what the entitlement
+ * client itself does for the same class of outage (it degrades to free limits
+ * rather than denying), and the error direction here is bounded in the shape
+ * that matters: the common case is a member on a cheap personal plan uploading
+ * into a group owned by someone on Family, so falling back to the caller checks
+ * against the *smaller* allowance. It can over-grant when the caller happens to
+ * hold the richer plan, which is why it logs at `error` — a run of these means
+ * group-service is down, not that a limit is wrong.
+ */
+function groupOwnerSubject(resolveGroupId) {
+    return async (req) => {
+        const caller = req.user?.email;
+        const groupId = await resolveGroupId(req);
+        if (!groupId)
+            return caller;
+        const owner = await (0, client_1.getGroupOwner)(String(groupId));
+        if (owner)
+            return owner.ownerEmail;
+        logger_1.default.error('Group owner unresolved; billing usage to the caller instead', {
+            event: 'entitlement.subject_fallback',
+            groupId: String(groupId),
+            caller,
+            route: req.originalUrl
+        });
+        return caller;
+    };
+}
+//# sourceMappingURL=subject.js.map

package/dist/groups/subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/groups/subject.ts"],"names":[],"mappings":";;;;;AAgCA,8CAiBC;AAhDD,+DAAuC;AAEvC,qCAAyC;AAIzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,iBAAiB,CAAC,cAA+B;IAC/D,OAAO,KAAK,EAAE,GAAY,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC;QAE5B,MAAM,KAAK,GAAG,MAAM,IAAA,sBAAa,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QACnD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC,UAAU,CAAC;QAEnC,gBAAM,CAAC,KAAK,CAAC,6DAA6D,EAAE;YAC1E,KAAK,EAAE,8BAA8B;YACrC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC;YACxB,MAAM;YACN,KAAK,EAAE,GAAG,CAAC,WAAW;SACvB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { requireEnv } from './config/env';
 export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError, PaymentRequiredError } from './errors/HttpError';
 export type { PaymentRequiredDetails } from './errors/HttpError';
 export * from './entitlements';
+export * from './groups';
 export { authenticateToken } from './middleware/authMiddleware';
 export { requireInternalServiceToken, internalServiceTokenBypass, allowUserOrInternalService, verifyInternalToken, INTERNAL_TOKEN_HEADER, SERVICE_ID_HEADER } from './middleware/internalServiceAuth';
 export { createCorsMiddleware } from './middleware/corsMiddleware';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC7K,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC7K,YAAY,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,cAAc,gBAAgB,CAAC;AAG/B,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -54,6 +54,8 @@ Object.defineProperty(exports, "TooManyRequestsError", { enumerable: true, get:
 Object.defineProperty(exports, "PaymentRequiredError", { enumerable: true, get: function () { return HttpError_1.PaymentRequiredError; } });
 // Entitlements (plan limits, usage meters, enforcement)
 __exportStar(require("./entitlements"), exports);
+// Group ownership (the quota subject for anything pooled)
+__exportStar(require("./groups"), exports);
 // Middleware
 var authMiddleware_1 = require("./middleware/authMiddleware");
 Object.defineProperty(exports, "authenticateToken", { enumerable: true, get: function () { return authMiddleware_1.authenticateToken; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;;;;;;;;;;;;;;;;;;AAErF,gBAAgB;AAChB,qDAAoD;AAA3C,8GAAA,aAAa,OAAA;AAEtB,2CAAkD;AAAzC,4GAAA,gBAAgB,OAAA;AAGzB,UAAU;AACV,2CAAqD;AAA5C,iHAAA,OAAO,OAAU;AAE1B,gBAAgB;AAChB,8DAAoF;AAA3E,+GAAA,WAAW,OAAA;AAAE,8GAAA,UAAU,OAAA;AAAE,kHAAA,cAAc,OAAA;AAChD,gEAA+D;AAAtD,sHAAA,iBAAiB,OAAA;AAG1B,WAAW;AACX,oDAAgE;AAAvD,uGAAA,SAAS,OAAA;AAAE,0GAAA,YAAY,OAAA;AAEhC,SAAS;AACT,oCAA0C;AAAjC,iGAAA,UAAU,OAAA;AAEnB,SAAS;AACT,gDAA6K;AAApK,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAGhJ,wDAAwD;AACxD,iDAA+B;AAE/B,aAAa;AACb,8DAAgE;AAAvD,mHAAA,iBAAiB,OAAA;AAC1B,wEAO0C;AANxC,kIAAA,2BAA2B,OAAA;AAC3B,iIAAA,0BAA0B,OAAA;AAC1B,iIAAA,0BAA0B,OAAA;AAC1B,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,wHAAA,iBAAiB,OAAA;AAEnB,8DAAmE;AAA1D,sHAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,4GAAA,YAAY,OAAA;AACrB,4DAA0G;AAAjG,8GAAA,aAAa,OAAA;AAAE,yHAAA,wBAAwB,OAAA;AAAE,oHAAA,mBAAmB,OAAA;AACrE,kDAAmH;AAA1G,2GAAA,eAAe,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AACnF,kDAAiD;AAAxC,oGAAA,QAAQ,OAAA;AAKjB,QAAQ;AACR,mDAAmF;AAA1E,oHAAA,qBAAqB,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AACrD,6CAA6E;AAApE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,qGAAA,SAAS,OAAA;AAElD,2DAA8E;AAArE,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAE5C,UAAU;AACV,qCAQmB;AAPjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,4GAAA,iBAAiB,OAAA;AACjB,gHAAA,qBAAqB,OAAA;AACrB,+GAAA,oBAAoB,OAAA;AACpB,0GAAA,eAAe,OAAA;AACf,mGAAA,QAAQ,OAAA;AAGV,UAAU;AACV,qCAUmB;AATjB,qGAAA,UAAU,OAAA;AACV,oGAAA,SAAS,OAAA;AACT,oGAAA,SAAS,OAAA;AACT,4GAAA,iBAAiB,OAAA;AACjB,0GAAA,eAAe,OAAA;AACf,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AACV,wGAAA,aAAa,OAAA;AACb,6GAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;;;;;;;;;;;;;;;;;;AAErF,gBAAgB;AAChB,qDAAoD;AAA3C,8GAAA,aAAa,OAAA;AAEtB,2CAAkD;AAAzC,4GAAA,gBAAgB,OAAA;AAGzB,UAAU;AACV,2CAAqD;AAA5C,iHAAA,OAAO,OAAU;AAE1B,gBAAgB;AAChB,8DAAoF;AAA3E,+GAAA,WAAW,OAAA;AAAE,8GAAA,UAAU,OAAA;AAAE,kHAAA,cAAc,OAAA;AAChD,gEAA+D;AAAtD,sHAAA,iBAAiB,OAAA;AAG1B,WAAW;AACX,oDAAgE;AAAvD,uGAAA,SAAS,OAAA;AAAE,0GAAA,YAAY,OAAA;AAEhC,SAAS;AACT,oCAA0C;AAAjC,iGAAA,UAAU,OAAA;AAEnB,SAAS;AACT,gDAA6K;AAApK,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAAE,iHAAA,oBAAoB,OAAA;AAGhJ,wDAAwD;AACxD,iDAA+B;AAE/B,0DAA0D;AAC1D,2CAAyB;AAEzB,aAAa;AACb,8DAAgE;AAAvD,mHAAA,iBAAiB,OAAA;AAC1B,wEAO0C;AANxC,kIAAA,2BAA2B,OAAA;AAC3B,iIAAA,0BAA0B,OAAA;AAC1B,iIAAA,0BAA0B,OAAA;AAC1B,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,wHAAA,iBAAiB,OAAA;AAEnB,8DAAmE;AAA1D,sHAAA,oBAAoB,OAAA;AAC7B,0DAAyD;AAAhD,4GAAA,YAAY,OAAA;AACrB,4DAA0G;AAAjG,8GAAA,aAAa,OAAA;AAAE,yHAAA,wBAAwB,OAAA;AAAE,oHAAA,mBAAmB,OAAA;AACrE,kDAAmH;AAA1G,2GAAA,eAAe,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,+GAAA,mBAAmB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AACnF,kDAAiD;AAAxC,oGAAA,QAAQ,OAAA;AAKjB,QAAQ;AACR,mDAAmF;AAA1E,oHAAA,qBAAqB,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AACrD,6CAA6E;AAApE,6GAAA,iBAAiB,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,qGAAA,SAAS,OAAA;AAElD,2DAA8E;AAArE,mHAAA,gBAAgB,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAE5C,UAAU;AACV,qCAQmB;AAPjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,4GAAA,iBAAiB,OAAA;AACjB,gHAAA,qBAAqB,OAAA;AACrB,+GAAA,oBAAoB,OAAA;AACpB,0GAAA,eAAe,OAAA;AACf,mGAAA,QAAQ,OAAA;AAGV,UAAU;AACV,qCAUmB;AATjB,qGAAA,UAAU,OAAA;AACV,oGAAA,SAAS,OAAA;AACT,oGAAA,SAAS,OAAA;AACT,4GAAA,iBAAiB,OAAA;AACjB,0GAAA,eAAe,OAAA;AACf,oGAAA,SAAS,OAAA;AACT,qGAAA,UAAU,OAAA;AACV,wGAAA,aAAa,OAAA;AACb,6GAAA,kBAAkB,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/app/createBaseApp.test.ts

@@ -63,6 +63,37 @@ describe('createBaseApp', () => {
     expect(res.status).toBe(200);
   });
 
+  it('trusts the proxy, so X-Forwarded-For identifies the client rather than being ignored', async () => {
+    const app = createBaseApp();
+    app.get('/whoami', (req, res) => res.json({ ip: req.ip }));
+
+    const res = await request(app).get('/whoami').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(res.body.ip).toBe('203.0.113.7');
+  });
+
+  it('keeps rate-limit buckets per client, not one shared bucket behind the proxy', async () => {
+    const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const clientA = await request(app).get('/ping').set('X-Forwarded-For', '203.0.113.7');
+    const clientB = await request(app).get('/ping').set('X-Forwarded-For', '198.51.100.4');
+    const clientAAgain = await request(app).get('/ping').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(clientA.status).toBe(200);
+    expect(clientB.status).toBe(200); // a different client is unaffected by A exhausting its window
+    expect(clientAAgain.status).toBe(429);
+  });
+
+  it('ignores X-Forwarded-For when trustProxy is disabled', async () => {
+    const app = createBaseApp({ trustProxy: false });
+    app.get('/whoami', (req, res) => res.json({ ip: req.ip }));
+
+    const res = await request(app).get('/whoami').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(res.body.ip).not.toBe('203.0.113.7');
+  });
+
   it('mounts /health/live ahead of the rate limiter, so it never gets 429s a busy service would', async () => {
     const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
     app.get('/ping', (_req, res) => res.json({ ok: true }));

package/src/app/createBaseApp.ts

@@ -25,6 +25,12 @@ export interface CreateBaseAppOptions {
   tracing?: boolean;
   /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
   metrics?: boolean;
+  /**
+   * Value for Express's `trust proxy`. Defaults to trusting private/loopback
+   * addresses — see the note on tumbaland-proxy below. Pass `false` for a
+   * service exposed directly to clients with no proxy in front of it.
+   */
+  trustProxy?: Parameters<Express['set']>[1];
 }
 
 /**
@@ -47,6 +53,24 @@ export interface CreateBaseAppOptions {
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
   const {
@@ -55,11 +79,14 @@ export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
     parseJson = true,
     parseCookies = true,
     tracing = true,
-    metrics = true
+    metrics = true,
+    trustProxy = 'loopback, linklocal, uniquelocal'
   } = options;
 
   const app = express();
 
+  app.set('trust proxy', trustProxy);
+
   app.get('/health/live', healthLive);
 
   app.use(securityHeaders);

package/src/entitlements/client.test.ts

@@ -150,6 +150,36 @@ describe('when payment-service cannot be reached', () => {
   });
 });
 
+describe('base URL selection', () => {
+  it('prefers the container-network address over the public hostname', async () => {
+    process.env.PAYMENT_INTERNAL_URL = 'http://payment-service:5005';
+    process.env.PAYMENT_API_URL = 'https://payment-api.tumbaland.eu';
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    await getEntitlements('user@example.com');
+
+    // payment-front templates the public variable into the browser's
+    // config.json, so it cannot be pointed inward — hence the second variable.
+    expect(global.fetch).toHaveBeenCalledWith(
+      'http://payment-service:5005/internal/entitlements?email=user%40example.com',
+      expect.anything()
+    );
+  });
+
+  it('falls back to the public URL, so local dev and un-migrated deploys still work', async () => {
+    delete process.env.PAYMENT_INTERNAL_URL;
+    process.env.PAYMENT_API_URL = 'https://payment-api.tumbaland.eu';
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    await getEntitlements('user@example.com');
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://payment-api.tumbaland.eu/internal/entitlements?email=user%40example.com',
+      expect.anything()
+    );
+  });
+});
+
 describe('cache bounds', () => {
   it('evicts the oldest entries instead of growing without limit', async () => {
     (global.fetch as jest.Mock).mockResolvedValue(paidResponse());

package/src/entitlements/client.ts

@@ -72,8 +72,25 @@ interface EntitlementResponse {
   upgradeTo?: string;
 }
 
+/**
+ * Prefers the container-network address over the public hostname.
+ *
+ * `PAYMENT_API_URL` cannot simply be pointed inward: payment-front's entrypoint
+ * templates that same variable into the `config.json` the *browser* downloads,
+ * so a Docker-internal value there breaks the subscription and checkout pages.
+ * One variable, two consumers with incompatible needs — this is the server-side
+ * half of it.
+ *
+ * Falling back keeps local dev (where only `PAYMENT_API_URL` is set) and any
+ * un-migrated deployment working; it just takes the long way round, out through
+ * the proxy and back, carrying the internal token across the public edge.
+ */
+function internalPaymentUrl(): string | undefined {
+  return process.env.PAYMENT_INTERNAL_URL || process.env.PAYMENT_API_URL;
+}
+
 async function fetchEntitlements(email: string): Promise<Entitlements> {
-  const baseUrl = process.env.PAYMENT_API_URL;
+  const baseUrl = internalPaymentUrl();
   const token = process.env.INTERNAL_SERVICE_TOKEN;
   const serviceId = process.env.SERVICE_NAME || 'unknown-service';
 

package/src/entitlements/index.ts

@@ -26,14 +26,16 @@ export type {
   PartialPlanLimits
 } from './definitions';
 
-export type { Entitlements, EntitlementsMode } from './types';
-export { getEntitlementsMode, resetEntitlementsModeWarning } from './mode';
+export type { Entitlements } from './types';
 
 export { UsageMeter, currentPeriod } from './UsageMeter';
 export type { IUsageMeter } from './UsageMeter';
 export { getUsage, getUsageSnapshot, checkQuota, consumeQuota, releaseQuota, setUsage } from './usage';
 export type { QuotaRequest } from './usage';
 
+export { reconcileUsageMeters, runUsageReconciliation, RECONCILED_METERS } from './reconcile';
+export type { ReconcileOptions, ReconcileReport, MeterChange, OrphanedMeter } from './reconcile';
+
 export { getEntitlements, invalidateEntitlements, clearEntitlementsCache } from './client';
 
 export { loadEntitlements, requireEntitlement, requireQuota, retentionFloor } from './middleware';

package/src/entitlements/middleware.test.ts

@@ -35,7 +35,7 @@ function mockReq(overrides: Partial<Request> = {}): Request {
 }
 
 beforeEach(() => {
-  process.env = { ...ORIGINAL_ENV, ENTITLEMENTS_MODE: 'enforce' };
+  process.env = { ...ORIGINAL_ENV };
   jest.clearAllMocks();
   mockGetEntitlements.mockResolvedValue(entitlements());
 });
@@ -89,24 +89,10 @@ describe('requireEntitlement', () => {
     );
   });
 
-  it('logs instead of blocking in observe mode', async () => {
-    process.env.ENTITLEMENTS_MODE = 'observe';
-    const next = jest.fn();
-
-    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
-
-    expect(next).toHaveBeenCalledWith();
-    expect(logger.info).toHaveBeenCalledWith('entitlement.would_block', expect.objectContaining({ feature: 'cleanExport' }));
-  });
-
-  it('does not even look entitlements up when the mode is off', async () => {
-    process.env.ENTITLEMENTS_MODE = 'off';
-    const next = jest.fn();
-
-    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
+  it('logs the denial alongside throwing it', async () => {
+    await requireEntitlement('cleanExport')(mockReq(), {} as Response, jest.fn());
 
-    expect(next).toHaveBeenCalledWith();
-    expect(mockGetEntitlements).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith('entitlement.blocked', expect.objectContaining({ feature: 'cleanExport' }));
   });
 });
 
@@ -143,15 +129,6 @@ describe('requireQuota', () => {
     expect(next).toHaveBeenCalledWith(denial);
   });
 
-  it('is inert when the mode is off', async () => {
-    process.env.ENTITLEMENTS_MODE = 'off';
-    const next = jest.fn();
-
-    await requireQuota('storageBytes')(mockReq(), {} as Response, next);
-
-    expect(mockCheckQuota).not.toHaveBeenCalled();
-    expect(next).toHaveBeenCalledWith();
-  });
 });
 
 describe('retentionFloor', () => {
@@ -171,9 +148,11 @@ describe('retentionFloor', () => {
     expect(await retentionFloor('user@example.com', now)).toBeNull();
   });
 
-  it('never truncates history outside enforce mode', async () => {
-    process.env.ENTITLEMENTS_MODE = 'observe';
+  it('still applies the floor when the limits are a stale fallback', async () => {
+    mockGetEntitlements.mockResolvedValue(entitlements({ stale: true }));
 
-    expect(await retentionFloor('user@example.com', now)).toBeNull();
+    // Fail closed, same as every other gate: an outage clips history to the
+    // free tier for a minute rather than handing the full archive out.
+    expect(await retentionFloor('user@example.com', now)).toEqual(new Date('2026-05-11T00:00:00.000Z'));
   });
 });

package/src/entitlements/middleware.ts

@@ -4,7 +4,6 @@ import { PaymentRequiredError, UnauthorizedError } from '../errors/HttpError';
 import { FeatureKey, MeterKey, UNLIMITED } from './definitions';
 import { getEntitlements } from './client';
 import { checkQuota } from './usage';
-import { getEntitlementsMode } from './mode';
 import { Entitlements } from './types';
 
 declare global {
@@ -51,23 +50,17 @@ export async function loadEntitlements(req: Request, resolve: SubjectResolver =
 export function requireEntitlement(feature: FeatureKey, options: EntitlementOptions = {}): RequestHandler {
   return async (req, _res, next) => {
     try {
-      const mode = getEntitlementsMode();
-      if (mode === 'off') return next();
-
       const entitlements = await loadEntitlements(req, options.subject);
       if (entitlements.limits.features[feature]) return next();
 
-      if (mode === 'observe') {
-        logger.info('entitlement.would_block', {
-          event: 'entitlement.would_block',
-          feature,
-          subjectId: entitlements.email,
-          planCode: entitlements.planCode,
-          route: req.originalUrl,
-          stale: entitlements.stale === true
-        });
-        return next();
-      }
+      logger.info('entitlement.blocked', {
+        event: 'entitlement.blocked',
+        feature,
+        subjectId: entitlements.email,
+        planCode: entitlements.planCode,
+        route: req.originalUrl,
+        stale: entitlements.stale === true
+      });
 
       throw new PaymentRequiredError(`Your plan does not include ${feature}`, {
         code: 'FEATURE_NOT_IN_PLAN',
@@ -98,8 +91,6 @@ export interface QuotaOptions extends EntitlementOptions {
 export function requireQuota(meter: MeterKey, options: QuotaOptions = {}): RequestHandler {
   return async (req, _res, next) => {
     try {
-      if (getEntitlementsMode() === 'off') return next();
-
       const entitlements = await loadEntitlements(req, options.subject);
       const amount = typeof options.amount === 'function' ? options.amount(req) : (options.amount ?? 1);
 
@@ -126,8 +117,6 @@ export function requireQuota(meter: MeterKey, options: QuotaOptions = {}): Reque
  * price history it depends on is not.
  */
 export async function retentionFloor(email: string, now: Date = new Date()): Promise<Date | null> {
-  if (getEntitlementsMode() !== 'enforce') return null;
-
   const { limits } = await getEntitlements(email);
   const days = limits.retentionDays;
   if (days === UNLIMITED || days < 0) return null;