@onesub/server 0.18.3 → 0.19.0

package/README.md

@@ -96,6 +96,9 @@ explicit app IDs fail closed and are never validated with another app's credenti
 | `GET  /onesub/admin/subscriptions/:transactionId` | Get subscription detail (requires `adminSecret`) |
 | `GET  /onesub/admin/customers/:userId` | Get a customer profile (requires `adminSecret`) |
 | `POST /onesub/admin/sync-apple/:originalTransactionId` | Refresh a subscription from Apple (requires `adminSecret`) |
+| `GET /onesub/admin/test-overrides` | List sandbox-only entitlement overrides (requires `adminSecret`) |
+| `PUT /onesub/admin/test-overrides/:userId` | Force an entitlement verdict for one user — body `{ "entitled": false }`. Honoured **only for Sandbox receipts**, so production customers are unaffected. Exists because Apple cannot cancel a sandbox subscription bought with a real Apple Account, which otherwise locks a tester out of the purchase flow. Process-local and non-persistent |
+| `DELETE /onesub/admin/test-overrides/:userId` | Clear that user's override (requires `adminSecret`) |
 | `GET  /onesub/admin/webhook-deadletters` | List failed webhook jobs in DLQ (requires `adminSecret` + BullMQ) |
 | `POST /onesub/admin/webhook-replay/:id` | Replay a dead-letter job (requires `adminSecret` + BullMQ) |
 | `GET  /onesub/entitlement?userId=&id=` | Evaluate one configured entitlement |

package/dist/__tests__/test-overrides.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sandbox-only entitlement overrides.
+ *
+ * Apple cannot cancel a sandbox subscription bought with a real Apple Account
+ * through TestFlight, so a tester who subscribes once stays entitled and can
+ * never re-run the purchase flow. That is not a hypothetical: it hid a paywall
+ * entry point from App Review (PenguinRun 2.0.6, Guideline 2.1(b)) because the
+ * reviewer had subscribed in an earlier round.
+ *
+ * The guarantee under test is the safety one — an override must be incapable of
+ * touching a paying customer. It is honoured only when the receipt just
+ * validated came from Sandbox.
+ */
+export {};
+//# sourceMappingURL=test-overrides.test.d.ts.map

package/dist/__tests__/test-overrides.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-overrides.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/test-overrides.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/index.cjs

@@ -458,7 +458,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 +1265,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 +1347,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) {
@@ -2358,6 +2383,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 {
@@ -3521,6 +3582,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).",