@peektravel/app-utilities 1.0.1 → 1.1.0

package/README.md

@@ -163,6 +163,12 @@ Two kinds of failures surface as exceptions:
 - `PiiAccessDisabledError` — a payment / booking-modification operation was
   called on an access service created without `fullCustomerAccess` (see [Access options
   / PII](#access-options--pii)). Carries `.operation` (the blocked method name).
+- `InstallWebhookError` — `parseInstallWebhook` got a validly signed token that
+  does not name the delivered install: the token has no `sub`
+  (`.reason === "missing_subject"`), or the body `install_id` is not equal to it
+  (`.reason === "install_id_mismatch"`). It extends `jsonwebtoken`'s
+  `JsonWebTokenError`, so an `instanceof JsonWebTokenError` check also matches
+  it. Respond `401`.
 
 Once a token's signature verifies, claim *extraction* never throws: the whole
 `user` block may be absent (`claims.user === null`) and every field inside it is
@@ -321,7 +327,7 @@ app.post("/install-webhook", async (req, res) => {
     const token = req.header("x-peek-auth") ?? "";
     event = parseInstallWebhook(token, req.body, process.env.PEEK_INTERNAL_SECRET!);
   } catch {
-    return res.sendStatus(401); // bad signature / issuer / audience / expired
+    return res.sendStatus(401); // bad token, or the body names another install
   }
   switch (event.status) {
     case "installed":        await provision(event); break;
@@ -350,11 +356,12 @@ expiry, issuer, and `"Joken"` audience (the same checks as `verifyPeekAuthToken`
 throwing the underlying `jsonwebtoken` error), then returns one flat, JSON-safe
 `InstallWebhook`: `installId`, `accountId` (**also called the partner ID**),
 `accountName`, `platform`, `isTest`, `timezone`, `apiUrl`, `status`, `rawStatus`,
-`displayVersion`, and a **nullable** `user`. The **JSON body is the source of the
-event data**; the fields it shares with the token (`installId` / `accountId` /
-`status` / `displayVersion` / `user`) fall back to the **verified token** when
-the body omits them. The token authenticates the whole delivery, so the body is
-trusted within a verified request. This webhook is the only source of
+`displayVersion`, and a **nullable** `user`. **`installId` is always the token
+`sub`**: a body `install_id` that is present and not equal to it throws
+`InstallWebhookError`, and so does a token with no `sub`. The **JSON body is the
+source of the other event data**; the fields it shares with the token
+(`accountId` / `status` / `displayVersion` / `user`) fall back to the **verified
+token** when the body omits them. This webhook is the only source of
 `accountId`, `timezone`, and `apiUrl` in the package, since no GraphQL read
 returns them — **persist them per install**. `apiUrl` is the install's **base API
 URL**: pass it straight through (don't reconstruct it from `appId`) as the access

package/dist/index.cjs

@@ -249,8 +249,6 @@ var AvailabilityService = class {
 function resolveAccessOptions(options) {
   return { fullCustomerAccess: options?.fullCustomerAccess ?? false };
 }
-
-// src/errors.ts
 var FORBIDDEN_STATUS = 403;
 var PERMISSION_MESSAGE_PREFIX = "CNG request forbidden: the app is missing the required permission";
 var PERMISSION_MESSAGE_UNKNOWN = "CNG request forbidden: the app is missing a required permission";
@@ -350,6 +348,21 @@ var AcmeApiError = class extends Error {
     this.body = body;
   }
 };
+var INSTALL_WEBHOOK_INSTALL_ID_MISMATCH = "install_id_mismatch";
+var INSTALL_WEBHOOK_MISSING_SUBJECT = "missing_subject";
+var INSTALL_WEBHOOK_MESSAGES = {
+  [INSTALL_WEBHOOK_INSTALL_ID_MISMATCH]: "Install webhook body install_id does not match the token subject",
+  [INSTALL_WEBHOOK_MISSING_SUBJECT]: "Install webhook token has no subject (install id)"
+};
+var InstallWebhookError = class extends jwt__namespace.default.JsonWebTokenError {
+  /** Why the delivery was rejected. */
+  reason;
+  constructor(reason) {
+    super(INSTALL_WEBHOOK_MESSAGES[reason]);
+    this.name = "InstallWebhookError";
+    this.reason = reason;
+  }
+};
 
 // src/models/peek/product.ts
 var ACTIVITY_PRODUCT_TYPE = "ACTIVITY";
@@ -2815,7 +2828,7 @@ async function requestWithRetry(http, url, init, label, onResponse) {
 // src/internal/sdk-headers.ts
 var SDK_HEADER_NAME = "x-peek-sdk";
 var SDK_PLATFORM = "js";
-var SDK_VERSION = "1.0.1";
+var SDK_VERSION = "1.1.0";
 var SDK_HEADER_VALUE = `${SDK_PLATFORM}-${SDK_VERSION}`;
 
 // src/internal/peek/graphql-client.ts
@@ -5305,10 +5318,11 @@ function toPeekPlatform(raw) {
 function parseInstallWebhook(token, body, secret) {
   const payload = verifyPeekJwt(token, secret);
   const parsed = extractInstallWebhookBody(body);
+  const installId = resolveInstallId(payload.sub, parsed.install_id);
   const account = parsed.account ?? {};
   const rawStatus = parsed.status || payload.status || "";
   return {
-    installId: parsed.install_id || payload.sub || "",
+    installId,
     accountId: account.id || payload.account?.id || "",
     accountName: account.name || "",
     platform: toPeekPlatform(account.platform || ""),
@@ -5321,6 +5335,14 @@ function parseInstallWebhook(token, body, secret) {
     user: resolveInstallUser(parsed.modified_by, payload.user)
   };
 }
+function resolveInstallId(rawSubject, bodyInstallId) {
+  const tokenSubject = cleanTokenString(rawSubject);
+  if (tokenSubject === null) throw new InstallWebhookError(INSTALL_WEBHOOK_MISSING_SUBJECT);
+  if (bodyInstallId && bodyInstallId !== tokenSubject) {
+    throw new InstallWebhookError(INSTALL_WEBHOOK_INSTALL_ID_MISMATCH);
+  }
+  return tokenSubject;
+}
 function resolveInstallUser(bodyUser, tokenUser) {
   if (cleanTokenString(bodyUser?.id) !== null) return mapPeekTokenUser(bodyUser);
   return mapPeekTokenUser(tokenUser);
@@ -5352,6 +5374,7 @@ exports.CngProductService = CngProductService;
 exports.CustomQuestionService = CustomQuestionService;
 exports.DailyNoteService = DailyNoteService;
 exports.INSTALL_STATUSES = INSTALL_STATUSES;
+exports.InstallWebhookError = InstallWebhookError;
 exports.MembershipService = MembershipService;
 exports.PeekAccessService = PeekAccessService;
 exports.PeekGraphQLError = PeekGraphQLError;