WPO V2 Authentication Library

NestJS authentication/authorization library with a global guard chain:

1. JwtAuthGuard
2. PermissionsGuard
3. RoleValidationGuard

It supports both:

• Standard JWT traffic.
• Gateway-forwarded enterprise API-key traffic (x-auth-type=api_key).

Installation

npm install @bigscoots/wpo-v2-authentication-lib

Configuration

PermissionModule.forRoot({
  namespace: process.env.AUTH_NAMESPACE,
  domain: process.env.AUTH_DOMAIN,
  audience: process.env.AUTH_AUDIENCE,
  gatewaySharedToken: process.env.GATEWAY_SHARED_TOKEN,
  // default is true when omitted
  // set false only if you want selective @AllowApiKeyAuth() opt-in
  allowApiKeyAuthGlobally: true,
  redis: {
    host: process.env.REDIS_HOST,
    port: Number(process.env.REDIS_PORT),
    password: process.env.REDIS_PASSWORD,
  },
});

gatewaySharedToken can also be provided via GATEWAY_SHARED_TOKEN env var.

JWT Flow (Unchanged)

• Request includes Authorization: Bearer <jwt>.
• JwtAuthGuard verifies JWT against configured JWKS/domain/audience.
• request.user is built from JWT claims.
• PermissionsGuard and RoleValidationGuard execute as before.

Gateway API-Key Flow

Use this for gateway-authenticated enterprise routes.

Required forwarded headers:

• x-auth-type: api_key
• x-client-id: <keyId>
• x-org-id: <orgId/userUuid>
• x-gateway-token: <sharedGatewayToken>

Security behavior:

• Header mode is accepted globally by default.
• You can disable global mode (allowApiKeyAuthGlobally=false) and then selectively opt-in routes with @AllowApiKeyAuth().
• x-gateway-token must match configured shared token using constant-time compare.
• No KV/DB API-key validation is performed in this library.

Principal mapping for API-key mode:

• request.user.uuid = x-org-id
• request.user.role = customer
• request.user.permissions = []
• request.authContext = { authType: 'api_key', clientId, orgId }

Route Example (Global Dual-Auth)

import { Controller, Get } from '@nestjs/common';
import {
  ApiKeyGatewayHeadersDecorator,
  Roles,
} from '@bigscoots/wpo-v2-authentication-lib';

@Controller('enterprise')
export class EnterpriseController {
  @Get('usage')
  @Roles('customer')
  @ApiKeyGatewayHeadersDecorator()
  getUsage() {
    return { ok: true };
  }
}

Optional strict mode:

• Set allowApiKeyAuthGlobally=false.
• Then add @AllowApiKeyAuth() only where API-key traffic should be accepted.

Request Examples

JWT request:

curl -X GET "https://service.example.com/v1/sites" \
  -H "Authorization: Bearer <jwt>"

Gateway-forwarded API-key request:

curl -X GET "https://service.example.com/enterprise/usage" \
  -H "x-auth-type: api_key" \
  -H "x-client-id: key_123" \
  -H "x-org-id: org_456" \
  -H "x-gateway-token: $GATEWAY_SHARED_TOKEN"

Migration Guide

See notes/gateway-api-key-migration-guide.md.