feat: expose jwt helpers for app starter kit

Author: coladarci

docs/internal/ARCHITECTURE.md

@@ -44,6 +44,11 @@ call typed methods like `peek.getProductService().getAllProducts()`.
 - Constructs a single shared `TokenManager` and `GraphQLClient`.
 - Exposes one `get<Resource>Service()` accessor per resource. Each is **lazily
   created and memoized** — repeated calls return the same instance.
+- Exposes `verifyPeekAuthToken(token)` to verify HMAC-signed JWTs issued by
+  the Peek app registry (`iss: "app_registry_v2"`), returning
+  a fully typed `PeekAuthTokenClaims` (including the nested `PeekAuthTokenUser`
+  object). Throws `JsonWebTokenError` / `TokenExpiredError` / `NotBeforeError`
+  from `jsonwebtoken` on failure.
 - Composes dependencies between services where needed:
   - `TimeslotService` receives the resource-pool and account-user services (for
     guide resolution).
@@ -196,8 +201,8 @@ Recurring patterns inside services:
 
 The barrel re-exports only the public contract: `PeekAccessService` + its config,
 each resource service class (and the options/result types callers need), all
-data-model **types**, the `Logger` interface + `noopLogger`, and the three typed
-error classes. Query strings and raw response interfaces are deliberately kept
+data-model **types** (including `PeekAuthTokenClaims` and `PeekAuthTokenUser`),
+the `Logger` interface + `noopLogger`, and the three typed error classes. Query strings and raw response interfaces are deliberately kept
 internal — including the booking-webhook registration query
 (`BOOKING_WEBHOOK_GQL_QUERY` stays internal, documented via `docs/webhooks.md`).
 The webhook-related public exports are the two parsers `parseBookingWebhook` and

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {

src/index.ts

@@ -115,6 +115,7 @@ export type {
 } from "./models/booking-addon.js";
 export type { Guide, Review } from "./models/review.js";
 export type { Waiver } from "./models/waiver.js";
+export type { PeekAuthTokenClaims, PeekAuthTokenUser } from "./models/auth-token.js";
 
 export { noopLogger } from "./logger.js";
 export type { Logger } from "./logger.js";

src/models/auth-token.ts

@@ -0,0 +1,33 @@
+/** User context embedded in a Peek auth token. */
+export interface PeekAuthTokenUser {
+  /** User's email address. */
+  email: string;
+  /** User's Peek account ID */
+  id: string;
+  /** Whether the user has admin privileges. */
+  isAdmin: boolean;
+  /** User's locale (e.g. `"en"`). */
+  locale: string;
+  /** User's display name. */
+  name: string;
+}
+
+/** Claims returned by {@link PeekAccessService.verifyPeekAuthToken}. */
+export interface PeekAuthTokenClaims {
+  /** Install ID — the JWT subject (`sub`). Peek-assigned UUID. */
+  installId: string;
+  /** JWT issuer — `"app_registry_v2"` for all Peek-issued tokens. */
+  issuer: string;
+  /** Unique JWT ID (`jti`). */
+  jwtId: string;
+  /** App display version at time of issuance. */
+  displayVersion: string;
+  /** Issued-at timestamp (Unix epoch seconds). */
+  issuedAt: number;
+  /** Expiration timestamp (Unix epoch seconds). */
+  expiresAt: number;
+  /** Not-before timestamp (Unix epoch seconds). */
+  notBefore: number;
+  /** Authenticated user context. */
+  user: PeekAuthTokenUser;
+}

src/peek-access-service.ts

@@ -7,6 +7,7 @@
  * service objects — e.g. {@link PeekAccessService.getProductService} — that
  * carry the resource-specific business logic.
  */
+import * as jwt from "jsonwebtoken";
 import { AccountUserService } from "./internal/account-users/account-user-service.js";
 import { AvailabilityService } from "./internal/availability/availability-service.js";
 import { BookingService } from "./internal/bookings/booking-service.js";
@@ -25,6 +26,7 @@ import { PromoCodeService } from "./internal/promo-codes/promo-code-service.js";
 import { V2_EXTENDABLE_SLUG } from "./internal/gateway-endpoints.js";
 import { TokenManager } from "./internal/token-manager.js";
 import { noopLogger, type Logger } from "./logger.js";
+import type { PeekAuthTokenClaims } from "./models/auth-token.js";
 
 /** Default backoffice GraphQL gateway base URL (v1). */
 const DEFAULT_BASE_URL = "https://apps.peekapis.com/backoffice-gql";
@@ -37,6 +39,19 @@ const DEFAULT_TOKEN_TTL_SECONDS = 3600;
 const DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS = 60;
 /** Default HTTP 429 retry backoff. */
 const DEFAULT_RETRY_DELAYS_MS = [1000, 2000, 4000];
+/** JWT issuer set by the Peek app registry on all tokens it issues. */
+const PEEK_TOKEN_ISSUER = "app_registry_v2";
+
+interface RawPeekTokenPayload {
+  sub: string;
+  iss: string;
+  jti: string;
+  iat: number;
+  exp: number;
+  nbf: number;
+  display_version: string;
+  user: { email: string; id: string; is_admin: boolean; locale: string; name: string };
+}
 
 /** Configuration for a {@link PeekAccessService} instance. */
 export interface PeekAccessServiceConfig {
@@ -104,6 +119,7 @@ export interface PeekAccessServiceConfig {
 export class PeekAccessService {
   private readonly client: GraphQLClient;
   private readonly productServiceOptions: ProductServiceOptions;
+  private readonly jwtSecret: string;
   private productService?: ProductService;
   private accountUserService?: AccountUserService;
   private resourcePoolService?: ResourcePoolService;
@@ -124,6 +140,8 @@ export class PeekAccessService {
     requireNonEmpty(config.appId, "appId");
     if (!isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey");
 
+    this.jwtSecret = config.jwtSecret;
+
     const logger = config.logger ?? noopLogger;
     const tokens = new TokenManager({
       secret: config.jwtSecret,
@@ -152,6 +170,48 @@ export class PeekAccessService {
     };
   }
 
+  /**
+   * Verifies a Peek auth token issued by the app registry and returns the
+   * decoded claims.
+   *
+   * Validates the HMAC signature (using this service's `jwtSecret`), the token
+   * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
+   * from the `jsonwebtoken` library on any failure — callers should catch to
+   * distinguish error kinds:
+   *
+   * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
+   *   malformed
+   * - `TokenExpiredError` — past `exp`
+   * - `NotBeforeError` — before `nbf`
+   *
+   * @throws {JsonWebTokenError} signature invalid or token malformed
+   * @throws {TokenExpiredError} token has expired
+   * @throws {NotBeforeError} token not yet valid
+   */
+  verifyPeekAuthToken(token: string): PeekAuthTokenClaims {
+    const payload = jwt.verify(token, this.jwtSecret, {
+      issuer: PEEK_TOKEN_ISSUER,
+    }) as RawPeekTokenPayload;
+
+    const { user: u } = payload;
+    return {
+      installId: payload.sub,
+      issuer: payload.iss,
+      jwtId: payload.jti,
+      displayVersion: payload.display_version,
+      issuedAt: payload.iat,
+      expiresAt: payload.exp,
+      notBefore: payload.nbf,
+      user: {
+        email: u.email,
+        id: u.id,
+        isAdmin: u.is_admin,
+        locale: u.locale,
+        name: u.name,
+      },
+    };
+  }
+
   /**
    * Returns the {@link ProductService} for this install, bound to the shared
    * authenticated transport. The instance is created lazily and reused.

test/peek-access-service.test.ts

@@ -1,3 +1,4 @@
+import * as jwt from "jsonwebtoken";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { AccountUserService } from "../src/internal/account-users/account-user-service.js";
@@ -258,6 +259,114 @@ describe("PeekAccessService.getProductService", () => {
   });
 });
 
+const PEEK_REGISTRY_ISSUER = "app_registry_v2";
+const PEEK_REGISTRY_AUDIENCE = "Joken"; // still used when minting test tokens
+
+const SAMPLE_USER_PAYLOAD = {
+  email: "admin@peek.com",
+  id: "null",
+  is_admin: false,
+  locale: "en",
+  name: "Admin User",
+};
+
+function mintRegistryToken(
+  secret: string,
+  overrides: Record<string, unknown> = {},
+): string {
+  return jwt.sign(
+    { display_version: "0.0.11", user: SAMPLE_USER_PAYLOAD, ...overrides },
+    secret,
+    {
+      subject: "8c1f32b4-ab3c-4e20-82b7-844ea9e03bc9",
+      issuer: PEEK_REGISTRY_ISSUER,
+      audience: PEEK_REGISTRY_AUDIENCE,
+      jwtid: "7d3d42c5-5724-489e-8380-a33abfc14936",
+      expiresIn: 60,
+      notBefore: 0,
+    },
+  );
+}
+
+describe("PeekAccessService.verifyPeekAuthToken", () => {
+  it("returns fully typed claims from a valid Peek registry token", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = mintRegistryToken(REQUIRED_CONFIG.jwtSecret);
+
+    const claims = service.verifyPeekAuthToken(token);
+
+    expect(claims.installId).toBe("8c1f32b4-ab3c-4e20-82b7-844ea9e03bc9");
+    expect(claims.issuer).toBe(PEEK_REGISTRY_ISSUER);
+    expect(claims.jwtId).toBe("7d3d42c5-5724-489e-8380-a33abfc14936");
+    expect(claims.displayVersion).toBe("0.0.11");
+    expect(typeof claims.issuedAt).toBe("number");
+    expect(typeof claims.expiresAt).toBe("number");
+    expect(typeof claims.notBefore).toBe("number");
+  });
+
+  it("maps the nested user object to typed fields", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = mintRegistryToken(REQUIRED_CONFIG.jwtSecret);
+
+    const { user } = service.verifyPeekAuthToken(token);
+
+    expect(user.email).toBe("admin@peek.com");
+    expect(user.id).toBe("null");
+    expect(user.isAdmin).toBe(false);
+    expect(user.locale).toBe("en");
+    expect(user.name).toBe("Admin User");
+  });
+
+  it("maps is_admin: true correctly", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = mintRegistryToken(REQUIRED_CONFIG.jwtSecret, {
+      user: { ...SAMPLE_USER_PAYLOAD, is_admin: true },
+    });
+
+    expect(service.verifyPeekAuthToken(token).user.isAdmin).toBe(true);
+  });
+
+  it("throws on a token signed with a different secret", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = mintRegistryToken("wrong-secret");
+
+    expect(() => service.verifyPeekAuthToken(token)).toThrow();
+  });
+
+  it("throws on a token with a different issuer", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = jwt.sign({ user: SAMPLE_USER_PAYLOAD }, REQUIRED_CONFIG.jwtSecret, {
+      issuer: "wrong-issuer",
+      audience: PEEK_REGISTRY_AUDIENCE,
+      expiresIn: 60,
+    });
+
+    expect(() => service.verifyPeekAuthToken(token)).toThrow();
+  });
+
+  it("throws on an expired token", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+    const token = jwt.sign(
+      { display_version: "0.0.11", user: SAMPLE_USER_PAYLOAD },
+      REQUIRED_CONFIG.jwtSecret,
+      {
+        subject: "8c1f32b4-ab3c-4e20-82b7-844ea9e03bc9",
+        issuer: PEEK_REGISTRY_ISSUER,
+        audience: PEEK_REGISTRY_AUDIENCE,
+        expiresIn: -1,
+      },
+    );
+
+    expect(() => service.verifyPeekAuthToken(token)).toThrow();
+  });
+
+  it("throws on a malformed token string", () => {
+    const service = new PeekAccessService(REQUIRED_CONFIG);
+
+    expect(() => service.verifyPeekAuthToken("not.a.jwt")).toThrow();
+  });
+});
+
 describe("PeekAccessService v2 mode", () => {
   it("uses the app-registry sandbox base URL by default", async () => {
     const { fetchFn, calls } = makeEmptyFetch();