@onesub/server 0.18.3 → 0.20.0

package/dist/index.cjs

@@ -180,9 +180,13 @@ var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
 async function fetchWithTimeout(input, init, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
   const controller = new AbortController();
   const callerSignal = init?.signal;
+  let onCallerAbort;
   if (callerSignal) {
     if (callerSignal.aborted) controller.abort(callerSignal.reason);
-    else callerSignal.addEventListener("abort", () => controller.abort(callerSignal.reason), { once: true });
+    else {
+      onCallerAbort = () => controller.abort(callerSignal.reason);
+      callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+    }
   }
   const timer = setTimeout(() => {
     controller.abort(new Error(`[onesub] fetch timed out after ${timeoutMs}ms`));
@@ -191,6 +195,7 @@ async function fetchWithTimeout(input, init, timeoutMs = DEFAULT_FETCH_TIMEOUT_M
     return await fetch(input, { ...init, signal: controller.signal });
   } finally {
     clearTimeout(timer);
+    if (onCallerAbort) callerSignal?.removeEventListener("abort", onCallerAbort);
   }
 }
 
@@ -243,6 +248,70 @@ function getDefaultCache() {
 function setDefaultCache(adapter) {
   defaultAdapter = adapter;
 }
+var DEFAULT_MAX_ENTRIES = 32;
+var DEFAULT_MAX_TTL_MS = 60 * 60 * 1e3;
+var VerifiedKeyCache = class {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  maxTtlMs;
+  now;
+  constructor(opts = {}) {
+    this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.maxTtlMs = opts.maxTtlMs ?? DEFAULT_MAX_TTL_MS;
+    this.now = opts.now ?? Date.now;
+  }
+  /**
+   * Return the key for `parts`, verifying via `produce` only on a miss.
+   *
+   * `parts` must contain every input the verification depends on — for Apple
+   * that is the JWS `alg` plus the full x5c chain. Anything left out would let
+   * one input's result be served for a different input.
+   */
+  async resolve(parts, produce) {
+    const cacheKey = digest(parts);
+    const now = this.now();
+    const hit = this.entries.get(cacheKey);
+    if (hit) {
+      if (hit.expiresAt > now) return hit.key;
+      this.entries.delete(cacheKey);
+    }
+    const verified = await produce();
+    const expiresAt = Math.min(now + this.maxTtlMs, verified.notAfter);
+    if (expiresAt > now) {
+      this.prune(now);
+      this.entries.set(cacheKey, { key: verified.key, expiresAt });
+    }
+    return verified.key;
+  }
+  /** Entries currently held, including any not yet pruned. Test/diagnostic use. */
+  get size() {
+    return this.entries.size;
+  }
+  /** Drop everything. Test/diagnostic use. */
+  clear() {
+    this.entries.clear();
+  }
+  /** Make room: expired entries first, then the oldest insertions. */
+  prune(now) {
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= now) this.entries.delete(key);
+    }
+    while (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) break;
+      this.entries.delete(oldest.value);
+    }
+  }
+};
+function digest(parts) {
+  const hash = crypto.createHash("sha256");
+  for (const part of parts) {
+    hash.update(String(part.length));
+    hash.update(":");
+    hash.update(part);
+  }
+  return hash.digest("base64");
+}
 function classifyMockReceipt(receipt) {
   if (receipt.startsWith(shared.MOCK_RECEIPT_PREFIX.NETWORK_ERROR)) return { kind: "network-error" };
   if (receipt.startsWith(shared.MOCK_RECEIPT_PREFIX.REVOKED)) return { kind: "revoked" };
@@ -262,8 +331,8 @@ function outcomePasses(outcome, tag) {
   return false;
 }
 function deterministicTransactionId(prefix, receipt) {
-  const digest = crypto.createHash("sha256").update(receipt).digest("hex").slice(0, 24);
-  return `${prefix}_${digest}`;
+  const digest2 = crypto.createHash("sha256").update(receipt).digest("hex").slice(0, 24);
+  return `${prefix}_${digest2}`;
 }
 function extractBoundToken(receipt) {
   return receipt.match(/#token=([^#]+)/)?.[1];
@@ -353,11 +422,15 @@ function verifyAppleCertChain(x5c) {
   }
   const chain = x5c.map((der) => new crypto.X509Certificate(derBase64ToPem(der)));
   const now = /* @__PURE__ */ new Date();
+  let notAfter = Infinity;
   for (let i = 0; i < chain.length; i++) {
     const cert = chain[i];
-    if (new Date(cert.validFrom) > now || new Date(cert.validTo) < now) {
+    const validTo = new Date(cert.validTo).getTime();
+    if (new Date(cert.validFrom) > now || validTo < now.getTime()) {
       throw new Error(`[onesub/apple] cert[${i}] outside validity window`);
     }
+    if (Number.isNaN(validTo)) notAfter = 0;
+    else if (validTo < notAfter) notAfter = validTo;
     if (i >= 1) assertIssuerCanSign(cert, i);
     if (i + 1 < chain.length) {
       if (!cert.checkIssued(chain[i + 1]) || !cert.verify(chain[i + 1].publicKey)) {
@@ -380,8 +453,9 @@ function verifyAppleCertChain(x5c) {
   if (!trustsRoot) {
     throw new Error("[onesub/apple] cert chain does not terminate at a trusted Apple root");
   }
-  return chain[0].toString();
+  return { leafPem: chain[0].toString(), notAfter };
 }
+var appleLeafKeys = new VerifiedKeyCache();
 async function decodeJws(jws, skipVerification = false) {
   if (skipVerification) {
     if (process.env["NODE_ENV"] === "production") {
@@ -396,9 +470,11 @@ async function decodeJws(jws, skipVerification = false) {
   if (!x5c || x5c.length === 0) {
     throw new Error("[onesub/apple] JWS header missing x5c certificate chain");
   }
-  const leafPem = verifyAppleCertChain(x5c);
   const alg = header.alg ?? "ES256";
-  const key = await jose.importX509(leafPem, alg);
+  const key = await appleLeafKeys.resolve([alg, ...x5c], async () => {
+    const { leafPem, notAfter } = verifyAppleCertChain(x5c);
+    return { key: await jose.importX509(leafPem, alg), notAfter };
+  });
   const { payload } = await jose.jwtVerify(jws, key);
   return payload;
 }
@@ -458,7 +534,10 @@ async function validateAppleReceipt(receipt, config) {
     purchasedAt: new Date(purchasedAt).toISOString(),
     willRenew: status === shared.SUBSCRIPTION_STATUS.ACTIVE,
     // refined by renewal info in webhook
-    ...appAccountToken ? { boundAccountId: appAccountToken } : {}
+    ...appAccountToken ? { boundAccountId: appAccountToken } : {},
+    // Transient, like boundAccountId: the validate route uses it to decide
+    // whether a sandbox-only test override may apply, then strips it.
+    ...tx.environment === "Sandbox" ? { sandbox: true } : {}
   };
 }
 async function validateAppleConsumableReceipt(signedTransaction, config, expectedProductId) {
@@ -1262,6 +1341,21 @@ function peekAppleBundleId(jws) {
   }
 }
 
+// src/test-overrides.ts
+var overrides = /* @__PURE__ */ new Map();
+function setTestOverride(userId, entitled) {
+  overrides.set(userId, entitled);
+}
+function clearTestOverride(userId) {
+  return overrides.delete(userId);
+}
+function getTestOverride(userId) {
+  return overrides.get(userId);
+}
+function listTestOverrides() {
+  return [...overrides].map(([userId, entitled]) => ({ userId, entitled }));
+}
+
 // src/routes/validate.ts
 var NO_SUB = { valid: false, subscription: null };
 var validateSchema = zod.z.object({
@@ -1329,6 +1423,13 @@ function createValidateRouter(config, store) {
         );
         return;
       }
+      const isSandbox = sub.sandbox === true;
+      delete sub.sandbox;
+      if (isSandbox && getTestOverride(userId) === false) {
+        log.warn(`[onesub/validate] sandbox test override active for ${userId}: forcing not-entitled`);
+        sub.status = shared.SUBSCRIPTION_STATUS.EXPIRED;
+        sub.willRenew = false;
+      }
       sub.userId = userId;
       await store.save(sub);
       if (platform === "google" && appConfig.google) {
@@ -2046,10 +2147,8 @@ function createPurchaseRouter(config, purchaseStore) {
   });
   return router;
 }
-async function evaluateEntitlement(userId, entitlement, store, purchaseStore) {
+function evaluateEntitlementFrom(subs, purchases, entitlement, now = Date.now()) {
   const productIdSet = new Set(entitlement.productIds);
-  const now = Date.now();
-  const subs = await store.getAllByUserId(userId);
   for (const sub of subs) {
     if (!productIdSet.has(sub.productId)) continue;
     const statusAllows = sub.status === shared.SUBSCRIPTION_STATUS.ACTIVE || sub.status === shared.SUBSCRIPTION_STATUS.GRACE_PERIOD;
@@ -2062,7 +2161,6 @@ async function evaluateEntitlement(userId, entitlement, store, purchaseStore) {
       expiresAt: sub.expiresAt
     };
   }
-  const purchases = await purchaseStore.getPurchasesByUserId(userId);
   for (const p of purchases) {
     if (p.type !== shared.PURCHASE_TYPE.NON_CONSUMABLE) continue;
     if (!productIdSet.has(p.productId)) continue;
@@ -2074,6 +2172,14 @@ async function evaluateEntitlement(userId, entitlement, store, purchaseStore) {
   }
   return { active: false, source: null };
 }
+async function evaluateEntitlement(userId, entitlement, store, purchaseStore) {
+  const now = Date.now();
+  const subs = await store.getAllByUserId(userId);
+  const fromSubs = evaluateEntitlementFrom(subs, [], entitlement, now);
+  if (fromSubs.active) return fromSubs;
+  const purchases = await purchaseStore.getPurchasesByUserId(userId);
+  return evaluateEntitlementFrom([], purchases, entitlement, now);
+}
 var userIdSchema = zod.z.string().min(1).max(256);
 var entitlementIdSchema = zod.z.string().min(1).max(128);
 function createEntitlementRouter(config, store, purchaseStore) {
@@ -2115,11 +2221,13 @@ function createEntitlementRouter(config, store, purchaseStore) {
       return;
     }
     try {
-      const entries = await Promise.all(
-        Object.entries(entitlements).map(async ([id, entitlement]) => {
-          const status = await evaluateEntitlement(userId, entitlement, store, purchaseStore);
-          return [id, status];
-        })
+      const [subs, purchases] = await Promise.all([
+        store.getAllByUserId(userId),
+        purchaseStore.getPurchasesByUserId(userId)
+      ]);
+      const now = Date.now();
+      const entries = Object.entries(entitlements).map(
+        ([id, entitlement]) => [id, evaluateEntitlementFrom(subs, purchases, entitlement, now)]
       );
       const response = {
         entitlements: Object.fromEntries(entries)
@@ -2310,9 +2418,10 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
       ]);
       let entitlements;
       if (config.entitlements && Object.keys(config.entitlements).length > 0) {
+        const now = Date.now();
         entitlements = {};
         for (const [id, def] of Object.entries(config.entitlements)) {
-          entitlements[id] = await evaluateEntitlement(params.userId, def, store, purchaseStore);
+          entitlements[id] = evaluateEntitlementFrom(subscriptions, purchases, def, now);
         }
       }
       const response = {
@@ -2358,6 +2467,42 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
       sendError(res, 500, shared.ONESUB_ERROR_CODE.INTERNAL_ERROR, err2.message ?? "sync error");
     }
   });
+  const overrideParamsSchema = zod.z.object({ userId: zod.z.string().min(1).max(256) });
+  const overrideBodySchema = zod.z.object({ entitled: zod.z.boolean() });
+  router.get(shared.ROUTES.ADMIN_TEST_OVERRIDES, (_req, res) => {
+    res.json({ overrides: listTestOverrides() });
+  });
+  router.put(shared.ROUTES.ADMIN_TEST_OVERRIDE, (req, res) => {
+    let params;
+    let body;
+    try {
+      params = overrideParamsSchema.parse(req.params);
+      body = overrideBodySchema.parse(req.body);
+    } catch (err2) {
+      if (err2 instanceof zod.z.ZodError) {
+        sendZodError(res, err2);
+      } else {
+        sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, "userId and { entitled: boolean } required");
+      }
+      return;
+    }
+    setTestOverride(params.userId, body.entitled);
+    log.warn(
+      `[onesub/admin] sandbox test override set for ${params.userId}: entitled=${body.entitled}`
+    );
+    res.json({ ok: true, userId: params.userId, entitled: body.entitled, sandboxOnly: true });
+  });
+  router.delete(shared.ROUTES.ADMIN_TEST_OVERRIDE, (req, res) => {
+    let params;
+    try {
+      params = overrideParamsSchema.parse(req.params);
+    } catch {
+      sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, "userId required");
+      return;
+    }
+    const cleared = clearTestOverride(params.userId);
+    res.json({ ok: true, userId: params.userId, cleared });
+  });
   if (webhookQueue?.listDeadLetters) {
     router.get("/onesub/admin/webhook-deadletters", async (_req, res) => {
       try {
@@ -2388,11 +2533,135 @@ function createAdminRouter(config, purchaseStore, store, webhookQueue) {
   }
   return router;
 }
+var MS_PER_DAY = 864e5;
+function bump(map, key) {
+  map[key] = (map[key] ?? 0) + 1;
+}
+function utcDateKey(ms) {
+  const d = new Date(ms);
+  const yyyy = d.getUTCFullYear();
+  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(d.getUTCDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}`;
+}
+function emptyDailyBuckets(fromMs, toMs) {
+  const out = [];
+  const start = new Date(fromMs);
+  start.setUTCHours(0, 0, 0, 0);
+  let cur = start.getTime();
+  while (cur <= toMs) {
+    out.push({ date: utcDateKey(cur), count: 0 });
+    cur += MS_PER_DAY;
+  }
+  return out;
+}
+function aggregateRange(records, opts) {
+  const byProduct = {};
+  const byPlatform = {};
+  let total = 0;
+  const buckets = opts.groupBy === "day" ? emptyDailyBuckets(opts.fromMs, opts.toMs) : null;
+  const bucketIndex = buckets ? new Map(buckets.map((b, i) => [b.date, i])) : null;
+  for (const record of records) {
+    if (opts.include && !opts.include(record)) continue;
+    const anchorMs = new Date(opts.anchor(record)).getTime();
+    if (Number.isNaN(anchorMs)) continue;
+    if (anchorMs < opts.fromMs || anchorMs > opts.toMs) continue;
+    total++;
+    bump(byProduct, record.productId);
+    bump(byPlatform, record.platform);
+    if (buckets && bucketIndex) {
+      const idx = bucketIndex.get(utcDateKey(anchorMs));
+      if (idx !== void 0) buckets[idx].count++;
+    }
+  }
+  return { total, byProduct, byPlatform, ...buckets ? { buckets } : {} };
+}
+function isActiveSubscription(sub, nowMs) {
+  const statusAllows = sub.status === shared.SUBSCRIPTION_STATUS.ACTIVE || sub.status === shared.SUBSCRIPTION_STATUS.GRACE_PERIOD;
+  return statusAllows && new Date(sub.expiresAt).getTime() > nowMs;
+}
+function isEndedSubscription(sub) {
+  return sub.status === shared.SUBSCRIPTION_STATUS.EXPIRED || sub.status === shared.SUBSCRIPTION_STATUS.CANCELED;
+}
+function isNonConsumable(purchase) {
+  return purchase.type === shared.PURCHASE_TYPE.NON_CONSUMABLE;
+}
+function aggregateActive(subs, purchases, nowMs) {
+  const byProduct = {};
+  const byProductPurchases = {};
+  const byPlatform = {};
+  let activeSubscriptions = 0;
+  let gracePeriodSubscriptions = 0;
+  let nonConsumablePurchases = 0;
+  for (const sub of subs) {
+    if (!isActiveSubscription(sub, nowMs)) continue;
+    activeSubscriptions++;
+    if (sub.status === shared.SUBSCRIPTION_STATUS.GRACE_PERIOD) gracePeriodSubscriptions++;
+    bump(byProduct, sub.productId);
+    bump(byPlatform, sub.platform);
+  }
+  for (const purchase of purchases) {
+    if (!isNonConsumable(purchase)) continue;
+    nonConsumablePurchases++;
+    bump(byProductPurchases, purchase.productId);
+    bump(byPlatform, purchase.platform);
+  }
+  return {
+    total: activeSubscriptions + nonConsumablePurchases,
+    activeSubscriptions,
+    gracePeriodSubscriptions,
+    nonConsumablePurchases,
+    byProduct,
+    byProductPurchases,
+    byPlatform
+  };
+}
+
+// src/metrics-cache.ts
+function isDisabled(ttlSeconds) {
+  return !Number.isFinite(ttlSeconds) || ttlSeconds <= 0;
+}
+function createMetricsCache(ttlSeconds, storage = new InMemoryCacheAdapter()) {
+  const inflight = /* @__PURE__ */ new Map();
+  const gridMs = Math.max(1, Math.floor(ttlSeconds * 1e3));
+  return {
+    quantizeToWindow(ms) {
+      if (isDisabled(ttlSeconds)) return ms;
+      return Math.floor(ms / gridMs) * gridMs;
+    },
+    async resolve(keyParts, produce) {
+      if (isDisabled(ttlSeconds)) return produce();
+      const key = `metrics:${keyParts.join(":")}`;
+      const cache = storage;
+      const hit = await cache.get(key);
+      if (hit !== null && hit !== void 0) return hit;
+      const pending = inflight.get(key);
+      if (pending) return pending;
+      const promise = (async () => {
+        const value = await produce();
+        await cache.set(key, value, ttlSeconds);
+        return value;
+      })();
+      inflight.set(key, promise);
+      try {
+        return await promise;
+      } finally {
+        inflight.delete(key);
+      }
+    }
+  };
+}
+
+// src/routes/metrics.ts
 var ADMIN_SECRET_HEADER2 = "x-admin-secret";
+var DEFAULT_METRICS_CACHE_TTL_SECONDS = 30;
 function createMetricsRouter(config, store, purchaseStore) {
   if (!config.adminSecret) return null;
   const router = express.Router();
   const adminSecret = config.adminSecret;
+  const metricsCache = createMetricsCache(
+    config.metricsCacheTtlSeconds ?? DEFAULT_METRICS_CACHE_TTL_SECONDS
+  );
   router.use("/onesub/metrics", (req, res, next) => {
     const provided = req.headers[ADMIN_SECRET_HEADER2];
     if (typeof provided !== "string" || !secretsEqual(provided, adminSecret)) {
@@ -2401,50 +2670,15 @@ function createMetricsRouter(config, store, purchaseStore) {
     }
     next();
   });
-  const isActiveSub = (sub, now) => {
-    const statusAllows = sub.status === shared.SUBSCRIPTION_STATUS.ACTIVE || sub.status === shared.SUBSCRIPTION_STATUS.GRACE_PERIOD;
-    return statusAllows && new Date(sub.expiresAt).getTime() > now;
-  };
-  const bump = (map, key) => {
-    map[key] = (map[key] ?? 0) + 1;
-  };
   router.get(shared.ROUTES.METRICS_ACTIVE, async (_req, res) => {
     try {
-      const [subs, purchases] = await Promise.all([
-        store.listAll(),
-        purchaseStore.listAll()
-      ]);
-      const now = Date.now();
-      const byProduct = {};
-      const byProductPurchases = {};
-      const byPlatform = {};
-      let activeSubscriptions = 0;
-      let gracePeriodSubscriptions = 0;
-      let nonConsumablePurchases = 0;
-      for (const sub of subs) {
-        if (!isActiveSub(sub, now)) continue;
-        activeSubscriptions++;
-        if (sub.status === shared.SUBSCRIPTION_STATUS.GRACE_PERIOD) {
-          gracePeriodSubscriptions++;
+      const response = await metricsCache.resolve(
+        ["active", metricsCache.quantizeToWindow(Date.now())],
+        async () => {
+          const [subs, purchases] = await Promise.all([store.listAll(), purchaseStore.listAll()]);
+          return aggregateActive(subs, purchases, Date.now());
         }
-        bump(byProduct, sub.productId);
-        bump(byPlatform, sub.platform);
-      }
-      for (const p of purchases) {
-        if (p.type !== shared.PURCHASE_TYPE.NON_CONSUMABLE) continue;
-        nonConsumablePurchases++;
-        bump(byProductPurchases, p.productId);
-        bump(byPlatform, p.platform);
-      }
-      const response = {
-        total: activeSubscriptions + nonConsumablePurchases,
-        activeSubscriptions,
-        gracePeriodSubscriptions,
-        nonConsumablePurchases,
-        byProduct,
-        byProductPurchases,
-        byPlatform
-      };
+      );
       res.status(200).json(response);
     } catch (err2) {
       log.error("[onesub/metrics/active] error:", err2);
@@ -2475,140 +2709,63 @@ function createMetricsRouter(config, store, purchaseStore) {
     }
     return { fromMs, toMs, groupBy };
   }
-  function utcDateKey(ms) {
-    const d = new Date(ms);
-    const yyyy = d.getUTCFullYear();
-    const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
-    const dd = String(d.getUTCDate()).padStart(2, "0");
-    return `${yyyy}-${mm}-${dd}`;
-  }
-  function emptyDailyBuckets(fromMs, toMs) {
-    const out = [];
-    const start = new Date(fromMs);
-    start.setUTCHours(0, 0, 0, 0);
-    let cur = start.getTime();
-    while (cur <= toMs) {
-      out.push({ date: utcDateKey(cur), count: 0 });
-      cur += 864e5;
-    }
-    return out;
-  }
-  router.get(shared.ROUTES.METRICS_STARTED, async (req, res) => {
-    const range = parseRange(req);
-    if ("error" in range) {
-      sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, range.error);
-      return;
-    }
-    try {
-      const subs = await store.listAll();
-      const byProduct = {};
-      const byPlatform = {};
-      let total = 0;
-      const buckets = range.groupBy === "day" ? emptyDailyBuckets(range.fromMs, range.toMs) : null;
-      const bucketIndex = buckets ? new Map(buckets.map((b, i) => [b.date, i])) : null;
-      for (const sub of subs) {
-        const purchasedMs = new Date(sub.purchasedAt).getTime();
-        if (purchasedMs < range.fromMs || purchasedMs > range.toMs) continue;
-        total++;
-        bump(byProduct, sub.productId);
-        bump(byPlatform, sub.platform);
-        if (buckets && bucketIndex) {
-          const idx = bucketIndex.get(utcDateKey(purchasedMs));
-          if (idx !== void 0) buckets[idx].count++;
-        }
-      }
-      const response = {
-        from: req.query["from"],
-        to: req.query["to"],
-        total,
-        byProduct,
-        byPlatform,
-        ...buckets ? { buckets } : {}
-      };
-      res.status(200).json(response);
-    } catch (err2) {
-      log.error("[onesub/metrics/started] error:", err2);
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
-    }
-  });
-  router.get(shared.ROUTES.METRICS_EXPIRED, async (req, res) => {
-    const range = parseRange(req);
-    if ("error" in range) {
-      sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, range.error);
-      return;
-    }
-    try {
-      const subs = await store.listAll();
-      const byProduct = {};
-      const byPlatform = {};
-      let total = 0;
-      const buckets = range.groupBy === "day" ? emptyDailyBuckets(range.fromMs, range.toMs) : null;
-      const bucketIndex = buckets ? new Map(buckets.map((b, i) => [b.date, i])) : null;
-      for (const sub of subs) {
-        if (sub.status !== shared.SUBSCRIPTION_STATUS.EXPIRED && sub.status !== shared.SUBSCRIPTION_STATUS.CANCELED) continue;
-        const expiredMs = new Date(sub.expiresAt).getTime();
-        if (expiredMs < range.fromMs || expiredMs > range.toMs) continue;
-        total++;
-        bump(byProduct, sub.productId);
-        bump(byPlatform, sub.platform);
-        if (buckets && bucketIndex) {
-          const idx = bucketIndex.get(utcDateKey(expiredMs));
-          if (idx !== void 0) buckets[idx].count++;
-        }
+  function windowed(name, load, anchor, include) {
+    return async (req, res) => {
+      const range = parseRange(req);
+      if ("error" in range) {
+        sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, range.error);
+        return;
       }
-      const response = {
-        from: req.query["from"],
-        to: req.query["to"],
-        total,
-        byProduct,
-        byPlatform,
-        ...buckets ? { buckets } : {}
-      };
-      res.status(200).json(response);
-    } catch (err2) {
-      log.error("[onesub/metrics/expired] error:", err2);
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
-    }
-  });
-  router.get(shared.ROUTES.METRICS_PURCHASES_STARTED, async (req, res) => {
-    const range = parseRange(req);
-    if ("error" in range) {
-      sendError(res, 400, shared.ONESUB_ERROR_CODE.INVALID_INPUT, range.error);
-      return;
-    }
-    try {
-      const purchases = await purchaseStore.listAll();
-      const byProduct = {};
-      const byPlatform = {};
-      let total = 0;
-      const buckets = range.groupBy === "day" ? emptyDailyBuckets(range.fromMs, range.toMs) : null;
-      const bucketIndex = buckets ? new Map(buckets.map((b, i) => [b.date, i])) : null;
-      for (const p of purchases) {
-        if (p.type !== shared.PURCHASE_TYPE.NON_CONSUMABLE) continue;
-        const purchasedMs = new Date(p.purchasedAt).getTime();
-        if (purchasedMs < range.fromMs || purchasedMs > range.toMs) continue;
-        total++;
-        bump(byProduct, p.productId);
-        bump(byPlatform, p.platform);
-        if (buckets && bucketIndex) {
-          const idx = bucketIndex.get(utcDateKey(purchasedMs));
-          if (idx !== void 0) buckets[idx].count++;
-        }
+      try {
+        const aggregate = await metricsCache.resolve(
+          [
+            name,
+            metricsCache.quantizeToWindow(range.fromMs),
+            metricsCache.quantizeToWindow(range.toMs),
+            range.groupBy
+          ],
+          async () => aggregateRange(await load(), {
+            fromMs: range.fromMs,
+            toMs: range.toMs,
+            groupBy: range.groupBy,
+            anchor,
+            ...include ? { include } : {}
+          })
+        );
+        const response = {
+          from: req.query["from"],
+          to: req.query["to"],
+          ...aggregate
+        };
+        res.status(200).json(response);
+      } catch (err2) {
+        log.error(`[onesub/metrics/${name}] error:`, err2);
+        sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
       }
-      const response = {
-        from: req.query["from"],
-        to: req.query["to"],
-        total,
-        byProduct,
-        byPlatform,
-        ...buckets ? { buckets } : {}
-      };
-      res.status(200).json(response);
-    } catch (err2) {
-      log.error("[onesub/metrics/purchases/started] error:", err2);
-      sendError(res, 500, shared.ONESUB_ERROR_CODE.STORE_ERROR, "Internal server error");
-    }
-  });
+    };
+  }
+  router.get(
+    shared.ROUTES.METRICS_STARTED,
+    windowed("started", () => store.listAll(), (sub) => sub.purchasedAt)
+  );
+  router.get(
+    shared.ROUTES.METRICS_EXPIRED,
+    windowed(
+      "expired",
+      () => store.listAll(),
+      (sub) => sub.expiresAt,
+      isEndedSubscription
+    )
+  );
+  router.get(
+    shared.ROUTES.METRICS_PURCHASES_STARTED,
+    windowed(
+      "purchases-started",
+      () => purchaseStore.listAll(),
+      (purchase) => purchase.purchasedAt,
+      isNonConsumable
+    )
+  );
   return router;
 }
 var OFFER_SECRET_HEADER = "x-onesub-offer-secret";
@@ -3521,6 +3678,54 @@ var ONESUB_OPENAPI = {
       }
     },
     // ── admin (mounted when config.adminSecret is set) ───────────────────────
+    [shared.ROUTES.ADMIN_TEST_OVERRIDES]: {
+      get: {
+        summary: "List sandbox-only entitlement overrides (admin).",
+        parameters: [ADMIN_SECRET_PARAM],
+        responses: {
+          200: { description: "OK" },
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
+    "/onesub/admin/test-overrides/{userId}": {
+      put: {
+        summary: "Force an entitlement verdict for one userId. Honoured ONLY for Sandbox receipts \u2014 a Production receipt ignores it. Exists because Apple cannot cancel a sandbox subscription bought with a real Apple Account, which otherwise locks a tester in.",
+        parameters: [
+          ADMIN_SECRET_PARAM,
+          { in: "path", name: "userId", required: true, schema: { type: "string" } }
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                required: ["entitled"],
+                properties: { entitled: { type: "boolean" } }
+              }
+            }
+          }
+        },
+        responses: {
+          200: { description: "OK" },
+          400: err("Invalid input (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      },
+      delete: {
+        summary: "Clear the sandbox entitlement override for one userId (admin).",
+        parameters: [
+          ADMIN_SECRET_PARAM,
+          { in: "path", name: "userId", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          200: { description: "OK" },
+          400: err("Invalid input (INVALID_INPUT)."),
+          401: err("Invalid admin secret (INVALID_ADMIN_SECRET).")
+        }
+      }
+    },
     [shared.ROUTES.ADMIN_SUBSCRIPTIONS]: {
       get: {
         summary: "Filtered, paginated subscription list (admin).",
@@ -4041,6 +4246,7 @@ exports.RedisWebhookEventStore = RedisWebhookEventStore;
 exports.createOneSubMiddleware = createOneSubMiddleware;
 exports.createOneSubServer = createOneSubServer;
 exports.evaluateEntitlement = evaluateEntitlement;
+exports.evaluateEntitlementFrom = evaluateEntitlementFrom;
 exports.fetchAppleSubscriptionStatus = fetchAppleSubscriptionStatus;
 exports.fetchAppleTransactionHistory = fetchAppleTransactionHistory;
 exports.getDefaultCache = getDefaultCache;