@i4e/invest4edu-access-core 0.25.0 → 0.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {

package/src/entitlement-store.d.ts

@@ -81,6 +81,13 @@ export interface EntitlementStore {
 }
 
 export function createEntitlementStore(opts: {
+  /**
+   * The subscription master switch. Returning false makes the whole store inert — every
+   * entitlement answers OPEN, nothing is counted and no subject is auto-provisioned — so the code
+   * can ship to production long before the product does. Defaults to the `SUBSCRIPTION_ENABLED`
+   * environment variable, and therefore to OFF.
+   */
+  isEnabled?: () => boolean | Promise<boolean>;
   /** Returns a raw MongoDB `Db`, or null/undefined when the connection is not ready. */
   getDb: () => unknown;
   /** Cast an id the way the caller's driver expects. Defaults to pass-through. */

package/src/entitlement-store.js

@@ -53,9 +53,34 @@ const noopLogger = { warn() {}, info() {} };
  *                                    would silently look unsubscribed.
  * @param {Object}   [opts.logger]   anything with `warn`
  */
-export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger = noopLogger } = {}) {
+export function createEntitlementStore({
+  getDb,
+  toObjectId = (v) => v,
+  logger = noopLogger,
+  /**
+   * THE subscription master switch.
+   *
+   * One place that makes the whole domain inert: no entitlement decides anything, no counter
+   * moves, no subject is auto-provisioned. Per-feature `rollout_mode` still governs which gates
+   * are live once this is on — this is the switch above all of them, for shipping the code long
+   * before the product.
+   *
+   * OFF by default, deliberately. A release must be able to carry every line of this and change
+   * nothing for a single user; a default of "on" would make that depend on remembering to set a
+   * flag, and the failure mode is customers being charged and refused.
+   *
+   * Resolved by the CALLER — env, a config document, whatever each service already uses — so this
+   * package keeps no opinion about where configuration lives.
+   */
+  isEnabled = () => String(process.env.SUBSCRIPTION_ENABLED || "").toLowerCase() === "true",
+} = {}) {
   if (typeof getDb !== "function") throw new Error("createEntitlementStore requires getDb()");
 
+  /** Resolved per call, never cached, so flipping the switch takes effect without a restart. */
+  const enabled = async () => {
+    try { return (await isEnabled()) === true; } catch { return false; }
+  };
+
   const oid = (v) => {
     try { return toObjectId(String(v)); } catch { return v; }
   };
@@ -82,6 +107,9 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
     bypass = false, now = new Date(),
   } = {}) {
     try {
+      // Master switch off ⇒ the same OPEN answer as "no subscription": allowed, unshaped,
+      // unmetered. Every caller already handles this, because it is the fail-open path.
+      if (!(await enabled())) return OPEN("subscription_disabled");
       const db = getDb();
       if (!db || !subjectType || !subjectId) return OPEN("no_subject");
 
@@ -324,6 +352,14 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
       const useRow = row || entitlement?.carriedRow;
       const ident = identity || entitlement?.carriedIdentity || {};
       // An unmetered feature has nothing to count; saying so is not a failure.
+      /**
+       * Checked before anything else, including the not-metered short-circuits: "the domain is
+       * off" is a truer answer than "this feature is not metered", and it has to hold even when
+       * the caller passed nothing useful. Returning `consumed: false` rather than throwing keeps
+       * callers on the path they already have for "the counter did not move".
+       */
+      if (!(await enabled())) return { consumed: false, reason: "subscription_disabled" };
+
       if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
       if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
 
@@ -466,6 +502,10 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
    */
   async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
     try {
+      // No auto-provisioning while the domain is off, whatever the catalogue says. This is the
+      // one that would otherwise write rows into production on the first distributor created.
+      if (!(await enabled())) return null;
+
       const db = getDb();
       if (!db || !subjectType || !subjectId) return null;