fix: PR B — trust boundaries (round 4, bugs 5, 6, 8, 9) (#79)

Bug 5 (HIGH): WebSocket joinProperty unauthenticated
- New WsAuthService (JWKS-backed, mirrors JwtStrategy)
- Gateway verifies JWT on handleConnection, disconnects invalid sockets
- joinProperty rejects unless user's JWT has the requested property_id
  (platform/admin roles bypass). AUTH_ENABLED=false preserves dev bypass.

Bug 6 (HIGH): Guest PII cross-property leakage
- All /guests/:id reads/updates/deletes + search now require propertyId
- assertGuestAtProperty verifies ≥1 reservation at requesting property
- Search uses inArray subquery scoped to reservations.propertyId
- Create intentionally unscoped (walk-ins have no reservation yet)

Bug 8 (HIGH): Stripe webhook signature verification broken
- express.raw installed on /api/v1/webhooks/stripe before global JSON
- Controller uses raw Buffer for stripe.webhooks.constructEvent

Bug 9 (HIGH): JWT audience not validated
- passport-jwt audience option enforced
- azp claim also validated in validate() for Keycloak compatibility
- KEYCLOAK_AUDIENCE documented in .env.example

CLAUDE.md: guests exception corrected to require reservation-link check.

553/553 tests passing, build + typecheck clean.

Co-authored-by: Dušan Milićević <dusanmilicevic33@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: telivity-otaip

.env.example

@@ -19,6 +19,10 @@ AUTH_ENABLED=false
 KEYCLOAK_URL=http://localhost:8080
 KEYCLOAK_REALM=haip
 KEYCLOAK_CLIENT_ID=haip-api
+# KEYCLOAK_AUDIENCE — optional explicit override for the expected `aud` claim.
+# If unset, KEYCLOAK_CLIENT_ID is used. JWTs whose `aud`/`azp` does not match
+# this value are rejected (prevents cross-client token replay within the realm).
+# KEYCLOAK_AUDIENCE=haip-api
 
 # Stripe Payment Gateway
 # STRIPE_MODE controls which gateway is used:

CLAUDE.md

@@ -50,7 +50,12 @@ for methods called only internally, because future controllers may call them.
   lookups (that creates a confused-deputy bug — the attacker supplies the id,
   the server derives a matching propertyId, scoping becomes a no-op).
 - Exceptions — document the reason in a code comment when you deviate:
-  - `guests` table: cross-property by design (one person stays at multiple hotels)
+  - `guests` table: the ROW is cross-property by design (one person stays at
+    multiple hotels), but API access MUST verify a reservation link at the
+    requesting property — i.e. scope reads/updates/deletes by "has this guest
+    at least one reservation at `propertyId`?". Creation is the only exception
+    (walk-ins have no reservation yet); the linking reservation is created
+    immediately after.
   - `properties` table: the property IS the tenant
   - Connect API (`/api/v1/connect/*`): bearer-credential model via
     `confirmationNumber` — scoped by credential possession, not propertyId

apps/api/package.json

@@ -29,12 +29,14 @@
     "@nestjs/serve-static": "^5.0.4",
     "@nestjs/swagger": "^7.4.0",
     "@nestjs/websockets": "^10.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
     "decimal.js": "^10.4.3",
     "drizzle-orm": "^0.39.0",
     "eventemitter2": "^6.4.9",
     "fast-xml-parser": "^5.5.10",
+    "jsonwebtoken": "^9.0.3",
     "jwks-rsa": "^4.0.1",
     "passport": "^0.7.0",
     "passport-jwt": "^4.0.1",

apps/api/src/main.ts

@@ -1,11 +1,26 @@
 import { NestFactory } from '@nestjs/core';
 import { ValidationPipe } from '@nestjs/common';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+// express is the underlying HTTP adapter used by NestJS's platform-express.
+// We don't declare @types/express directly; import the runtime bindings and
+// type them loosely here — these middlewares are only referenced from main.ts.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { json, raw } = require('express') as {
+  json: (...args: any[]) => any;
+  raw: (...args: any[]) => any;
+};
 import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
+  // Stripe webhook signature verification requires the exact raw request body.
+  // Install raw-body middleware for the webhook path BEFORE the global JSON
+  // parser so req.body is a Buffer for that route; every other route still
+  // receives parsed JSON.
+  app.use('/api/v1/webhooks/stripe', raw({ type: 'application/json' }));
+  app.use(json());
+
   // Global prefix for all routes
   app.setGlobalPrefix('api/v1');
 

apps/api/src/modules/auth/auth.module.ts

@@ -5,6 +5,7 @@ import { APP_GUARD } from '@nestjs/core';
 import { JwtStrategy } from './jwt.strategy';
 import { JwtAuthGuard } from './auth.guard';
 import { RolesGuard } from './roles.guard';
+import { WsAuthService } from './ws-auth.service';
 
 /**
  * Authentication & Authorization module.
@@ -46,6 +47,11 @@ import { RolesGuard } from './roles.guard';
     // Global guards — applied to ALL endpoints
     { provide: APP_GUARD, useClass: JwtAuthGuard },
     { provide: APP_GUARD, useClass: RolesGuard },
+    // WebSocket token verifier — used by gateways that cannot rely on
+    // passport HTTP guards (e.g. EventsGateway). Registered always; the
+    // gateway itself honours AUTH_ENABLED=false as a dev bypass.
+    WsAuthService,
   ],
+  exports: [WsAuthService],
 })
 export class AuthModule {}

apps/api/src/modules/auth/index.ts

@@ -5,3 +5,4 @@ export { Public } from './public.decorator';
 export { Roles } from './roles.decorator';
 export { CurrentUser } from './current-user.decorator';
 export type { AuthUser } from './current-user.decorator';
+export { WsAuthService } from './ws-auth.service';

apps/api/src/modules/auth/jwt.strategy.ts

@@ -1,4 +1,4 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { PassportStrategy } from '@nestjs/passport';
 import { ExtractJwt, Strategy } from 'passport-jwt';
@@ -10,18 +10,30 @@ import type { AuthUser } from './current-user.decorator';
  *
  * Fetches Keycloak's public signing keys via JWKS endpoint.
  * Extracts user info and realm roles from the JWT claims.
+ *
+ * Audience enforcement:
+ * - `aud` is validated against KEYCLOAK_CLIENT_ID (or KEYCLOAK_AUDIENCE if set).
+ * - Keycloak also emits `azp` (authorized party) identifying the client that
+ *   obtained the token. We enforce `azp === expected` in validate() so tokens
+ *   from other realm clients cannot be replayed against this API.
  */
 @Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
+  private readonly expectedAudience: string;
+
   constructor(configService: ConfigService) {
     const keycloakUrl = configService.get<string>('KEYCLOAK_URL', 'http://localhost:8080');
     const realm = configService.get<string>('KEYCLOAK_REALM', 'haip');
     const issuer = `${keycloakUrl}/realms/${realm}`;
+    const audience =
+      configService.get<string>('KEYCLOAK_AUDIENCE') ||
+      configService.get<string>('KEYCLOAK_CLIENT_ID', 'haip-api');
 
     super({
       jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
       ignoreExpiration: false,
       issuer,
+      audience,
       algorithms: ['RS256'],
       secretOrKeyProvider: passportJwtSecret({
         cache: true,
@@ -30,13 +42,20 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
         jwksUri: `${issuer}/protocol/openid-connect/certs`,
       }),
     });
+
+    this.expectedAudience = audience;
   }
 
   /**
-   * Passport calls this after JWT signature is verified.
+   * Passport calls this after JWT signature + issuer + audience are verified.
+   * We additionally enforce `azp` (Keycloak's authorized-party claim) so that
+   * access tokens minted for a different realm client cannot pass through.
    * Returns the user object attached to req.user.
    */
   validate(payload: any): AuthUser {
+    if (payload.azp && payload.azp !== this.expectedAudience) {
+      throw new UnauthorizedException('Invalid token audience (azp mismatch)');
+    }
     return {
       sub: payload.sub,
       email: payload.email ?? '',

apps/api/src/modules/auth/ws-auth.service.ts

@@ -0,0 +1,80 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as jwt from 'jsonwebtoken';
+import jwksClient, { JwksClient, SigningKey } from 'jwks-rsa';
+import type { AuthUser } from './current-user.decorator';
+
+/**
+ * Token verifier used by non-HTTP entrypoints (e.g. WebSocket gateway) that
+ * cannot go through the passport HTTP strategy. Mirrors JwtStrategy's
+ * validation rules: Keycloak issuer, audience (aud + azp), RS256 signature
+ * fetched from JWKS.
+ */
+@Injectable()
+export class WsAuthService {
+  private readonly logger = new Logger(WsAuthService.name);
+  private readonly issuer: string;
+  private readonly expectedAudience: string;
+  private readonly jwks: JwksClient;
+
+  constructor(configService: ConfigService) {
+    const keycloakUrl = configService.get<string>('KEYCLOAK_URL', 'http://localhost:8080');
+    const realm = configService.get<string>('KEYCLOAK_REALM', 'haip');
+    this.issuer = `${keycloakUrl}/realms/${realm}`;
+    this.expectedAudience =
+      configService.get<string>('KEYCLOAK_AUDIENCE') ||
+      configService.get<string>('KEYCLOAK_CLIENT_ID', 'haip-api');
+    this.jwks = jwksClient({
+      jwksUri: `${this.issuer}/protocol/openid-connect/certs`,
+      cache: true,
+      rateLimit: true,
+      jwksRequestsPerMinute: 5,
+    });
+  }
+
+  /**
+   * Verify a bearer token and return the extracted AuthUser.
+   * Throws on invalid signature, issuer, audience, or expiration.
+   */
+  async verify(token: string): Promise<AuthUser> {
+    const payload = await new Promise<any>((resolve, reject) => {
+      jwt.verify(
+        token,
+        (header, cb) => {
+          if (!header.kid) {
+            cb(new Error('Token has no kid'));
+            return;
+          }
+          this.jwks.getSigningKey(header.kid, (err: Error | null, key?: SigningKey) => {
+            if (err || !key) {
+              cb(err ?? new Error('Signing key not found'));
+              return;
+            }
+            cb(null, key.getPublicKey());
+          });
+        },
+        {
+          algorithms: ['RS256'],
+          issuer: this.issuer,
+          audience: this.expectedAudience,
+        },
+        (err, decoded) => {
+          if (err) reject(err);
+          else resolve(decoded);
+        },
+      );
+    });
+
+    if (payload.azp && payload.azp !== this.expectedAudience) {
+      throw new Error('Invalid token audience (azp mismatch)');
+    }
+
+    return {
+      sub: payload.sub,
+      email: payload.email ?? '',
+      name: payload.name ?? payload.preferred_username ?? '',
+      roles: payload.realm_access?.roles ?? [],
+      propertyIds: payload.property_ids ?? undefined,
+    };
+  }
+}

apps/api/src/modules/events/events.gateway.ts

@@ -8,8 +8,24 @@ import {
   MessageBody,
 } from '@nestjs/websockets';
 import { Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
 import { Server, Socket } from 'socket.io';
+import { WsAuthService } from '../auth/ws-auth.service';
+import type { AuthUser } from '../auth/current-user.decorator';
 
+/**
+ * Events gateway — real-time PMS event broadcasts.
+ *
+ * Security model:
+ * - On connect: verify a JWT passed via `handshake.auth.token` or `?token=`.
+ *   Invalid/missing tokens cause immediate disconnect.
+ * - On joinProperty: the requested propertyId must appear in the user's
+ *   JWT `property_ids` custom claim (mapped onto AuthUser.propertyIds).
+ *   Admin/platform roles can join any property.
+ * - Dev bypass: when AUTH_ENABLED=false (matching the HTTP JwtAuthGuard),
+ *   connections skip verification to keep local dev frictionless. Production
+ *   defaults to enforced.
+ */
 @WebSocketGateway({
   cors: {
     origin: ['http://localhost:5173', 'http://localhost:3000'],
@@ -18,12 +34,42 @@ import { Server, Socket } from 'socket.io';
 })
 export class EventsGateway implements OnGatewayConnection, OnGatewayDisconnect {
   private readonly logger = new Logger(EventsGateway.name);
+  private readonly authEnabled: boolean;
 
   @WebSocketServer()
   server!: Server;
 
-  handleConnection(client: Socket) {
-    this.logger.log(`Client connected: ${client.id}`);
+  constructor(
+    private readonly wsAuth: WsAuthService,
+    private readonly configService: ConfigService,
+  ) {
+    this.authEnabled =
+      this.configService.get<string>('AUTH_ENABLED', 'true') !== 'false';
+  }
+
+  async handleConnection(client: Socket) {
+    if (!this.authEnabled) {
+      this.logger.log(`Client connected (auth disabled): ${client.id}`);
+      return;
+    }
+
+    const token = this.extractToken(client);
+    if (!token) {
+      this.logger.warn(`Rejecting WS ${client.id}: no token`);
+      client.disconnect(true);
+      return;
+    }
+
+    try {
+      const user = await this.wsAuth.verify(token);
+      client.data.user = user;
+      this.logger.log(`Client connected: ${client.id} (sub=${user.sub})`);
+    } catch (err: any) {
+      this.logger.warn(
+        `Rejecting WS ${client.id}: token verification failed — ${err?.message ?? err}`,
+      );
+      client.disconnect(true);
+    }
   }
 
   handleDisconnect(client: Socket) {
@@ -36,6 +82,25 @@ export class EventsGateway implements OnGatewayConnection, OnGatewayDisconnect {
     @MessageBody() data: { propertyId: string },
   ) {
     if (!data?.propertyId) return;
+
+    if (this.authEnabled) {
+      const user = client.data.user as AuthUser | undefined;
+      if (!user) {
+        client.emit('error', { message: 'Not authenticated' });
+        return;
+      }
+      if (!this.userCanAccessProperty(user, data.propertyId)) {
+        this.logger.warn(
+          `WS ${client.id} (sub=${user.sub}) denied joinProperty ${data.propertyId}`,
+        );
+        client.emit('error', {
+          message: 'Forbidden: not a member of this property',
+          propertyId: data.propertyId,
+        });
+        return;
+      }
+    }
+
     const room = `property:${data.propertyId}`;
     client.join(room);
     this.logger.debug(`Client ${client.id} joined room ${room}`);
@@ -60,4 +125,30 @@ export class EventsGateway implements OnGatewayConnection, OnGatewayDisconnect {
       timestamp: new Date().toISOString(),
     });
   }
+
+  private extractToken(client: Socket): string | null {
+    const authToken = (client.handshake.auth as any)?.token;
+    if (typeof authToken === 'string' && authToken.length > 0) {
+      return authToken.replace(/^Bearer\s+/i, '');
+    }
+    const queryToken = client.handshake.query?.['token'];
+    if (typeof queryToken === 'string' && queryToken.length > 0) {
+      return queryToken;
+    }
+    const headerAuth = client.handshake.headers?.authorization;
+    if (typeof headerAuth === 'string' && headerAuth.length > 0) {
+      return headerAuth.replace(/^Bearer\s+/i, '');
+    }
+    return null;
+  }
+
+  private userCanAccessProperty(user: AuthUser, propertyId: string): boolean {
+    // Platform-level roles that bypass property scoping (same intent as the
+    // HTTP RolesGuard — admins can cross tenants for ops).
+    const platformRoles = new Set(['admin', 'platform_admin', 'superadmin']);
+    if (user.roles?.some((r) => platformRoles.has(r))) return true;
+
+    const allowed = user.propertyIds ?? [];
+    return allowed.includes(propertyId);
+  }
 }

apps/api/src/modules/events/events.module.ts

@@ -1,8 +1,11 @@
 import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
 import { EventsGateway } from './events.gateway';
 import { EventsService } from './events.service';
+import { AuthModule } from '../auth/auth.module';
 
 @Module({
+  imports: [ConfigModule, AuthModule],
   providers: [EventsGateway, EventsService],
   exports: [EventsGateway],
 })