@i4e/invest4edu-access-core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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": {
@@ -12,7 +12,9 @@
     "./access-config": "./src/access-config.js",
     "./access-schema": "./src/access-schema.js",
     "./access-resolver": "./src/access-resolver.js",
-    "./visible-when": "./src/visible-when.js"
+    "./visible-when": "./src/visible-when.js",
+    "./entitlement": "./src/entitlement.js",
+    "./entitlement-schema": "./src/entitlement-schema.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/access-resolver.js

@@ -173,9 +173,16 @@ export function resolveAccessSnapshot({
     : mergeGrants(grants, { mappedProducts, now });
 
   const byCode = new Map(features.map((f) => [f.feature_code, f]));
-  const productScope = bypass
+  // Product scope comes from the IDENTITY, for admins too. The loader already resolves an
+  // unmapped identity (internal staff, platform admins) to every product code, so this is "all"
+  // for them without any special case. Deriving a bypass admin's scope from the products declared
+  // ON FEATURES — as this used to — yields [] whenever no feature declares one, which is the state
+  // of the registry today: a system admin resolved to NO products, and every feature then inherited
+  // `products: []`. Kept only as a fallback for the case where identity scope is genuinely empty.
+  const identityScope = [...new Set(mappedProducts.map(String))];
+  const productScope = bypass && !identityScope.length
     ? [...new Set(features.flatMap((f) => f.products || []))]
-    : [...new Set(mappedProducts.map(String))];
+    : identityScope;
 
   const featureMap = {};
   const allowedScreens = [];

package/src/entitlement-schema.js

@@ -0,0 +1,183 @@
+/**
+ * Entitlement / subscription schema DEFINITIONS — @i4e/invest4edu-access-core (P6).
+ *
+ * Plain objects like access-schema.js (D4: no Mongoose in the package). Each backend registers its
+ * own models from these, so field names cannot drift between v1 and v2.
+ *
+ * RBAC answers "may they?"; entitlement answers "is it unlocked, and are they in quota?". Both must
+ * pass. See TDD §6, and §6.2a for the 2026-07-29 amendment that generalised quota period + subject
+ * and added the service-facing meter.
+ *
+ * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md
+ */
+
+/** How often a quota allowance resets. Carried in the period key, so no cron is needed. */
+export const PERIOD_GRANULARITIES = Object.freeze(["day", "month", "year", "term", "lifetime"]);
+
+/** Whose allowance is being spent. `account` = per firm (the legacy assumption); `user` = per seat. */
+export const QUOTA_SCOPES = Object.freeze(["account", "user"]);
+
+/** What happens when the allowance runs out. */
+export const OVERAGE_POLICIES = Object.freeze(["block", "single_usage", "unlimited"]);
+
+export const SUBSCRIPTION_STATUSES = Object.freeze([
+  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
+]);
+
+/**
+ * The timezone every calendar boundary is evaluated in.
+ *
+ * A daily quota is meaningless without one: in UTC an Indian partner's "10 a day" would reset at
+ * 05:30 local, so they would lose the tail of every working day. Matches the `tz` the MIS pipelines
+ * already use.
+ */
+export const QUOTA_TIMEZONE = "Asia/Kolkata";
+
+/** Reasons an entitlement decision can carry. Stable strings — they surface in APIs and logs. */
+export const ENTITLEMENT_REASONS = Object.freeze({
+  OK: "ok",
+  NO_SUBSCRIPTION: "no_subscription",
+  NOT_IN_PLAN: "not_in_plan",
+  LOCKED: "locked",
+  QUOTA_EXCEEDED: "quota_exceeded",
+  SUBSCRIPTION_BLOCKED: "subscription_blocked",
+  ADMIN_BYPASS: "admin_bypass",
+  NOT_METERED: "not_metered",
+  ENGINE_OFF: "engine_off",
+  RESOLVE_FAILED: "resolve_failed",
+});
+
+/** Global: the plans on sale. */
+export const PLAN_CATALOG_DEF = Object.freeze({
+  collection: "plan_catalog",
+  fields: Object.freeze({
+    plan_code: { type: "String", required: true, unique: true, index: true, immutable: true },
+    name: { type: "String", required: true },
+    description: { type: "String" },
+    billing_cycle: { type: "String", enum: ["monthly", "quarterly", "annual"], default: "annual" },
+    price: { type: "Number", default: 0 },
+    currency: { type: "String", default: "INR" },
+    position: { type: "Number", default: 0 },
+    status: { type: "String", enum: ["active", "dormant", "retired"], default: "active" },
+  }),
+});
+
+/**
+ * Global: `(plan, cycle, feature)` → what that plan grants for that feature.
+ *
+ * VERSIONED by `effective_date`: resolve the row with the greatest `effective_date <= now`. Prices
+ * and quotas change, and a past invoice must remain explicable — so rows are superseded, never
+ * edited in place.
+ */
+export const PLAN_ENTITLEMENT_DEF = Object.freeze({
+  collection: "plan_entitlements",
+  fields: Object.freeze({
+    plan_code: { type: "String", required: true, index: true },
+    billing_cycle: { type: "String", required: true },
+    feature_code: { type: "String", required: true, index: true },
+
+    unlocked: { type: "Boolean", default: true },
+    // null = unlimited. 0 is a real value: "in the plan, but no allowance".
+    quota: { type: "Number", default: null },
+    period_granularity: { type: "String", enum: PERIOD_GRANULARITIES, default: "month" },
+    quota_scope: { type: "String", enum: QUOTA_SCOPES, default: "account" },
+    overage_policy: { type: "String", enum: OVERAGE_POLICIES, default: "block" },
+    single_usage_price: { type: "Number", default: null },
+
+    effective_date: { type: "Date", required: true, index: true },
+    superseded_date: { type: "Date", default: null },
+  }),
+  indexes: Object.freeze([
+    { keys: { plan_code: 1, billing_cycle: 1, feature_code: 1, effective_date: -1 } },
+  ]),
+});
+
+/** Tenant: one subscription per firm. Replaces AccountPlan + distributor.selected_plan. */
+export const ACCOUNT_SUBSCRIPTION_DEF = Object.freeze({
+  collection: "account_subscriptions",
+  fields: Object.freeze({
+    account_id: { type: "ObjectId", required: true, index: true },
+    plan_code: { type: "String", required: true },
+    billing_cycle: { type: "String", required: true },
+    status: { type: "String", enum: SUBSCRIPTION_STATUSES, default: "trialing", index: true },
+    start_date: { type: "Date", required: true },
+    end_date: { type: "Date", default: null },
+    is_trial: { type: "Boolean", default: false },
+    trial_ends_at: { type: "Date", default: null },
+    // Per-firm overrides of the plan row: [{ feature_code, quota, unlocked, … }]. Sales concessions
+    // belong here, NOT as an edit to the shared plan row.
+    entitlement_overrides: { type: "[Mixed]", default: [] },
+  }),
+});
+
+/**
+ * Tenant: the quota counters. MUST live in the app DB — `consume` has to be atomic with the read,
+ * so this cannot be a side/analytics store.
+ *
+ * `subject_key` is the account id or the user id depending on `quota_scope`, so one collection
+ * serves both without a second shape.
+ */
+export const SUBSCRIPTION_USAGE_DEF = Object.freeze({
+  collection: "subscription_usage",
+  fields: Object.freeze({
+    subscription_id: { type: "ObjectId", required: true, index: true },
+    subject_key: { type: "String", required: true },
+    feature_code: { type: "String", required: true },
+    period: { type: "String", required: true },
+    used: { type: "Number", default: 0 },
+    last_consumed_at: { type: "Date", default: null },
+  }),
+  indexes: Object.freeze([
+    { keys: { subscription_id: 1, subject_key: 1, feature_code: 1, period: 1 }, options: { unique: true } },
+  ]),
+});
+
+/**
+ * Tenant: the exactly-once ledger for `consume`.
+ *
+ * A tool that times out and retries must not charge the partner twice, so every consume carries an
+ * idempotency key and the unique index — not application logic — is what enforces it.
+ */
+export const USAGE_IDEMPOTENCY_DEF = Object.freeze({
+  collection: "usage_idempotency",
+  fields: Object.freeze({
+    idempotency_key: { type: "String", required: true, unique: true, index: true },
+    account_id: { type: "ObjectId", index: true },
+    feature_code: { type: "String", required: true },
+    subject_key: { type: "String" },
+    period: { type: "String" },
+    n: { type: "Number", default: 1 },
+    // The decision returned the first time, replayed verbatim on a duplicate key.
+    result: { type: "Mixed", default: null },
+    created_date: { type: "Date", default: "now" },
+  }),
+});
+
+/** Global: the service callers allowed to meter, and which features each may meter. */
+export const METER_CLIENT_DEF = Object.freeze({
+  collection: "meter_clients",
+  fields: Object.freeze({
+    client_code: { type: "String", required: true, unique: true, index: true },
+    name: { type: "String", required: true },
+    // Key Vault SECRET NAME, never the secret. An admin API must never be able to read it back.
+    key_vault_ref: { type: "String", required: true },
+    // A tool may only meter what it is registered for — a leaked NFD-AI key cannot spend PFA quota.
+    allowed_features: { type: "[String]", default: [] },
+    status: { type: "String", enum: ["active", "disabled"], default: "active" },
+  }),
+});
+
+export default {
+  PERIOD_GRANULARITIES,
+  QUOTA_SCOPES,
+  OVERAGE_POLICIES,
+  SUBSCRIPTION_STATUSES,
+  QUOTA_TIMEZONE,
+  ENTITLEMENT_REASONS,
+  PLAN_CATALOG_DEF,
+  PLAN_ENTITLEMENT_DEF,
+  ACCOUNT_SUBSCRIPTION_DEF,
+  SUBSCRIPTION_USAGE_DEF,
+  USAGE_IDEMPOTENCY_DEF,
+  METER_CLIENT_DEF,
+};

package/src/entitlement.js

@@ -0,0 +1,166 @@
+/**
+ * Entitlement resolution — @i4e/invest4edu-access-core (P6). Pure: no DB, no Mongoose.
+ *
+ * RBAC says whether a user MAY do a thing. This says whether the FIRM's plan has it unlocked and
+ * whether the allowance is spent. Both must pass (TDD §4.2).
+ *
+ * The one hard rule (§4.3): entitlement **fails open**. An outage in the entitlement path must
+ * never block a feature a customer has paid for — the worst acceptable outcome is that we
+ * occasionally fail to charge. `overage_policy: 'block'` is the only branch that denies, and only
+ * on a definite quota-exceeded answer.
+ */
+import {
+  ENTITLEMENT_REASONS as R,
+  QUOTA_TIMEZONE,
+  PERIOD_GRANULARITIES,
+} from "./entitlement-schema.js";
+
+export { ENTITLEMENT_REASONS } from "./entitlement-schema.js";
+
+/**
+ * Calendar parts of `date` in QUOTA_TIMEZONE.
+ *
+ * Deliberately via Intl rather than date arithmetic: an offset constant would be wrong the moment
+ * anything changes, and a naive `toISOString()` would put an Indian partner's daily reset at 05:30
+ * local — silently costing them the tail of every working day.
+ */
+function partsInZone(date, timeZone = QUOTA_TIMEZONE) {
+  const fmt = new Intl.DateTimeFormat("en-CA", {
+    timeZone, year: "numeric", month: "2-digit", day: "2-digit",
+  });
+  const [{ value: y }, , { value: m }, , { value: d }] = fmt.formatToParts(date);
+  return { y, m, d };
+}
+
+/**
+ * The bucket key an allowance is counted in. The granularity lives IN the key, so a reset needs no
+ * cron: at midnight the key simply changes and the new bucket starts at zero.
+ *
+ * @param {string} granularity   day | month | year | term | lifetime
+ * @param {Object} [opts]
+ * @param {Date}   [opts.now]
+ * @param {string} [opts.subscriptionId]  required for `term`
+ * @param {string} [opts.timeZone]
+ */
+export function periodKey(granularity, { now = new Date(), subscriptionId = null, timeZone } = {}) {
+  const g = PERIOD_GRANULARITIES.includes(granularity) ? granularity : "month";
+  if (g === "lifetime") return "lifetime";
+  // A term quota with no subscription would silently collapse every firm into one shared bucket.
+  if (g === "term") return subscriptionId ? `term:${String(subscriptionId)}` : "lifetime";
+
+  const { y, m, d } = partsInZone(now, timeZone);
+  if (g === "year") return y;
+  if (g === "month") return `${y}-${m}`;
+  return `${y}-${m}-${d}`;
+}
+
+/** Whose allowance this is: the firm, or the individual seat. */
+export function subjectKeyFor(quotaScope, { accountId, userId } = {}) {
+  return String((quotaScope === "user" ? userId : accountId) ?? "");
+}
+
+/**
+ * Pick the live entitlement row for a feature: greatest `effective_date <= now`, not superseded.
+ * Rows are versioned rather than edited so a past invoice stays explicable.
+ */
+export function resolveEntitlementRow(rows = [], featureCode, now = new Date()) {
+  return rows
+    .filter((r) => r
+      && r.feature_code === featureCode
+      && new Date(r.effective_date) <= now
+      && (!r.superseded_date || new Date(r.superseded_date) > now))
+    .sort((a, b) => new Date(b.effective_date) - new Date(a.effective_date))[0] || null;
+}
+
+/** Apply a per-firm override on top of the plan row. Concessions live on the subscription. */
+function withOverride(row, overrides = [], featureCode) {
+  const o = (overrides || []).find((x) => x && x.feature_code === featureCode);
+  if (!o) return row;
+  const merged = { ...row };
+  for (const k of ["unlocked", "quota", "period_granularity", "quota_scope", "overage_policy", "single_usage_price"]) {
+    if (o[k] !== undefined) merged[k] = o[k];
+  }
+  return merged;
+}
+
+/**
+ * Decide entitlement for one feature.
+ *
+ * @param {Object} p
+ * @param {Object|null} p.subscription       account_subscriptions row
+ * @param {Array}  p.entitlementRows         plan_entitlements rows for this plan+cycle
+ * @param {string} p.featureCode
+ * @param {Object} p.feature                 registry row — `is_meterable` decides if quota applies
+ * @param {number} p.used                    already consumed in this period (caller supplies)
+ * @param {Object} p.identity                { accountId, userId }
+ * @param {boolean} [p.bypass]               D27 admin break-glass
+ * @param {Date}   [p.now]
+ * @returns {Object} { unlocked, quota, used, remaining, allowed, overage_policy, reason,
+ *                     period, subject_key, metered }
+ */
+export function resolveEntitlement({
+  subscription, entitlementRows = [], featureCode, feature = {},
+  used = 0, identity = {}, bypass = false, now = new Date(),
+} = {}) {
+  const base = {
+    quota: null, used, remaining: null, period: null, subject_key: null,
+    overage_policy: "unlimited", metered: false,
+  };
+  const open = (reason) => ({ ...base, unlocked: true, allowed: true, reason });
+
+  // D27: the break-glass resolves every gate open, including this one.
+  if (bypass) return open(R.ADMIN_BYPASS);
+
+  // `always_available` exists so login/billing/profile survive a blocked subscription — otherwise a
+  // past-due firm could not reach the screen that takes their money.
+  if (feature.always_available) return open(R.OK);
+
+  // No subscription: fail OPEN. Absence of a row is far more likely to be our gap than a customer
+  // genuinely owning nothing, and denying would break every un-migrated firm on day one.
+  if (!subscription) return open(R.NO_SUBSCRIPTION);
+
+  if (subscription.status === "blocked" || subscription.status === "expired") {
+    return { ...base, unlocked: false, allowed: false, reason: R.SUBSCRIPTION_BLOCKED };
+  }
+
+  const row = withOverride(
+    resolveEntitlementRow(entitlementRows, featureCode, now),
+    subscription.entitlement_overrides,
+    featureCode,
+  );
+  // Not named in the plan: OPEN. A plan that forgot to list a feature is a config gap, and P6 must
+  // not silently switch features off for everyone the moment it ships.
+  if (!row) return open(R.NOT_IN_PLAN);
+
+  if (row.unlocked === false) {
+    return { ...base, unlocked: false, allowed: false, overage_policy: row.overage_policy, reason: R.LOCKED };
+  }
+
+  // Unlocked but not metered → nothing to count.
+  if (!feature.is_meterable || row.quota === null || row.quota === undefined) {
+    return { ...open(feature.is_meterable ? R.OK : R.NOT_METERED), overage_policy: row.overage_policy || "unlimited" };
+  }
+
+  const granularity = row.period_granularity || "month";
+  const period = periodKey(granularity, { now, subscriptionId: subscription._id });
+  const subject_key = subjectKeyFor(row.quota_scope, identity);
+  const remaining = Math.max(0, Number(row.quota) - Number(used || 0));
+  const withinQuota = Number(used || 0) < Number(row.quota);
+  const policy = row.overage_policy || "block";
+
+  return {
+    unlocked: true,
+    quota: Number(row.quota),
+    used: Number(used || 0),
+    remaining,
+    // Only `block` denies. single_usage/unlimited let the call through — billing catches up after.
+    allowed: withinQuota || policy !== "block",
+    overage_policy: policy,
+    reason: withinQuota ? R.OK : R.QUOTA_EXCEEDED,
+    period,
+    subject_key,
+    metered: true,
+  };
+}
+
+export default { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor };