permissions-contractx 2.2.0 → 2.3.0

package/README.md

@@ -84,6 +84,99 @@ import { PermissionWrites } from 'permissions-contractx';
 search() { /* ... */ }
 ```
 
+## Inter-Service Authentication (HMAC)
+
+Además del modelo de autorización basado en JWT de usuario, el paquete incluye el sistema de autenticación **machine-to-machine (M2M)** que usan los microservicios de ContractX para llamarse entre sí de forma segura.
+
+Cada llamada saliente lleva headers `X-Service-*` con una firma HMAC-SHA256 del par `apiKey + secretKey` del servicio emisor. El receptor verifica la firma, el timestamp (ventana de expiración + drift de reloj) y el nonce (anti-replay). Ningún JWT de usuario interviene en estas llamadas.
+
+Para detalles de implementación, arquitectura y deuda conocida, ver [`src/inter-service-auth/README.md`](./src/inter-service-auth/README.md).
+
+### Configurar el módulo
+
+```typescript
+import { InterServiceAuthModule, SERVICE_NAMES } from 'permissions-contractx';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    InterServiceAuthModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: (cfg: ConfigService) => ({
+        services: {
+          [SERVICE_NAMES.AUTH]: {
+            serviceId: SERVICE_NAMES.AUTH,
+            apiKey:    cfg.get('AUTH_API_KEY'),
+            secretKey: cfg.get('AUTH_SECRET_KEY'),
+          },
+          [SERVICE_NAMES.CONTRACTS]: {
+            serviceId: SERVICE_NAMES.CONTRACTS,
+            apiKey:    cfg.get('CONTRACTS_API_KEY'),
+            secretKey: cfg.get('CONTRACTS_SECRET_KEY'),
+          },
+        },
+        signatureExpireMinutes:  5,
+        allowedTimeDriftSeconds: 30,
+        enableLogging: cfg.get('SERVICE_AUTH_LOGGING') === 'true',
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+El middleware (`InterServiceAuthMiddleware`) debe registrarse en el módulo consumidor:
+
+```typescript
+import { InterServiceAuthMiddleware } from 'permissions-contractx';
+
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(InterServiceAuthMiddleware).forRoutes('*');
+  }
+}
+```
+
+### Proteger un endpoint (solo M2M)
+
+```typescript
+import {
+  ServiceAuthGuard,
+  RequireServiceAuth,
+  RequireServicePermissions,
+} from 'permissions-contractx';
+
+@Controller('internal')
+@RequireServiceAuth()           // rechaza cualquier request no-M2M
+@UseGuards(ServiceAuthGuard)
+export class InternalController {
+  @Get('contracts')
+  @RequireServicePermissions('contracts.read')
+  listContracts() { /* ... */ }
+}
+```
+
+### Emitir una llamada M2M saliente
+
+```typescript
+constructor(private readonly authSvc: InterServiceAuthService) {}
+
+async fetchFromContracts(schema: string) {
+  const headers = this.authSvc.generateAuthHeaders(SERVICE_NAMES.CONTRACTS, schema);
+  return this.httpService.get('/internal/contracts', { headers }).toPromise();
+}
+```
+
+### Decoradores disponibles
+
+| Decorador | Propósito |
+|---|---|
+| `@RequireServiceAuth()` | Endpoint exclusivo M2M; rechaza JWT de usuario |
+| `@AllowServiceAuth(false)` | Bloquea M2M en un endpoint específico (gana sobre clase) |
+| `@RequireServicePermissions(...p)` | El servicio llamante debe tener todos los permisos listados |
+| `@RequireServiceRoles(...r)` | El servicio llamante debe tener al menos uno de los roles listados |
+
 ## Modelo de cuatro estados (migración)
 
 El `AuthorizationGuard` permite migrar cada endpoint de forma gradual mediante la variable de entorno de enforcement:

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export * from './decorators';
 export * from './services';
 export * from './interfaces';
 export * from './constants';
+export * from './inter-service-auth';
 export type { JwtPayload, AuthenticatedRequest, PermissionsModuleOptions, JwtAuthConfig } from './interfaces';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./decorators"), exports);
 __exportStar(require("./services"), exports);
 __exportStar(require("./interfaces"), exports);
 __exportStar(require("./constants"), exports);
+__exportStar(require("./inter-service-auth"), exports);

package/dist/inter-service-auth/index.d.ts

@@ -0,0 +1,8 @@
+export * from './inter-service-auth.types';
+export * from './inter-service-auth.config.interface';
+export { InterServiceAuthService, INTER_SERVICE_AUTH_CONFIG } from './inter-service-auth.service';
+export * from './inter-service-auth.module';
+export * from './inter-service-auth.middleware';
+export { ServiceAuthGuard, SERVICE_PERMISSIONS_KEY, SERVICE_ROLES_KEY, ALLOW_SERVICE_AUTH_KEY, REQUIRE_SERVICE_AUTH_KEY, } from './service-auth.guard';
+export * from './service-auth.decorators';
+//# sourceMappingURL=index.d.ts.map

package/dist/inter-service-auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAClG,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,cAAc,2BAA2B,CAAC"}

package/dist/inter-service-auth/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRE_SERVICE_AUTH_KEY = exports.ALLOW_SERVICE_AUTH_KEY = exports.SERVICE_ROLES_KEY = exports.SERVICE_PERMISSIONS_KEY = exports.ServiceAuthGuard = exports.INTER_SERVICE_AUTH_CONFIG = exports.InterServiceAuthService = void 0;
+__exportStar(require("./inter-service-auth.types"), exports);
+__exportStar(require("./inter-service-auth.config.interface"), exports);
+var inter_service_auth_service_1 = require("./inter-service-auth.service");
+Object.defineProperty(exports, "InterServiceAuthService", { enumerable: true, get: function () { return inter_service_auth_service_1.InterServiceAuthService; } });
+Object.defineProperty(exports, "INTER_SERVICE_AUTH_CONFIG", { enumerable: true, get: function () { return inter_service_auth_service_1.INTER_SERVICE_AUTH_CONFIG; } });
+__exportStar(require("./inter-service-auth.module"), exports);
+__exportStar(require("./inter-service-auth.middleware"), exports);
+var service_auth_guard_1 = require("./service-auth.guard");
+Object.defineProperty(exports, "ServiceAuthGuard", { enumerable: true, get: function () { return service_auth_guard_1.ServiceAuthGuard; } });
+Object.defineProperty(exports, "SERVICE_PERMISSIONS_KEY", { enumerable: true, get: function () { return service_auth_guard_1.SERVICE_PERMISSIONS_KEY; } });
+Object.defineProperty(exports, "SERVICE_ROLES_KEY", { enumerable: true, get: function () { return service_auth_guard_1.SERVICE_ROLES_KEY; } });
+Object.defineProperty(exports, "ALLOW_SERVICE_AUTH_KEY", { enumerable: true, get: function () { return service_auth_guard_1.ALLOW_SERVICE_AUTH_KEY; } });
+Object.defineProperty(exports, "REQUIRE_SERVICE_AUTH_KEY", { enumerable: true, get: function () { return service_auth_guard_1.REQUIRE_SERVICE_AUTH_KEY; } });
+__exportStar(require("./service-auth.decorators"), exports);

package/dist/inter-service-auth/inter-service-auth.config.interface.d.ts

@@ -0,0 +1,10 @@
+import { IServiceCredentials } from './inter-service-auth.types';
+export interface IServiceAuthConfig {
+    services: Record<string, IServiceCredentials>;
+    /** Minutes before a signed request expires (looking backward). Default: 5 */
+    signatureExpireMinutes?: number;
+    /** Seconds of future clock skew tolerated (looking forward). Default: 30 */
+    allowedTimeDriftSeconds?: number;
+    enableLogging?: boolean;
+}
+//# sourceMappingURL=inter-service-auth.config.interface.d.ts.map

package/dist/inter-service-auth/inter-service-auth.config.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-service-auth.config.interface.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/inter-service-auth.config.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC9C,6EAA6E;IAC7E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/dist/inter-service-auth/inter-service-auth.config.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/inter-service-auth/inter-service-auth.middleware.d.ts

@@ -0,0 +1,11 @@
+import { NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { InterServiceAuthService } from './inter-service-auth.service';
+export declare class InterServiceAuthMiddleware implements NestMiddleware {
+    private readonly interServiceAuthService;
+    private readonly logger;
+    constructor(interServiceAuthService: InterServiceAuthService);
+    use(req: Request, res: Response, next: NextFunction): void | Response<any, Record<string, any>>;
+    private normalizeHeaders;
+}
+//# sourceMappingURL=inter-service-auth.middleware.d.ts.map

package/dist/inter-service-auth/inter-service-auth.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-service-auth.middleware.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/inter-service-auth.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,cAAc,EAAiC,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,qBACa,0BAA2B,YAAW,cAAc;IAGnD,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IAFpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;gBAEtC,uBAAuB,EAAE,uBAAuB;IAE7E,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY;IA4CnD,OAAO,CAAC,gBAAgB;CAczB"}

package/dist/inter-service-auth/inter-service-auth.middleware.js

@@ -0,0 +1,75 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterServiceAuthMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const inter_service_auth_service_1 = require("./inter-service-auth.service");
+let InterServiceAuthMiddleware = class InterServiceAuthMiddleware {
+    constructor(interServiceAuthService) {
+        this.interServiceAuthService = interServiceAuthService;
+        this.logger = new common_1.Logger('InterServiceAuthMiddleware');
+    }
+    use(req, res, next) {
+        try {
+            const isServiceAuth = req.headers['x-service-auth'] === 'true';
+            if (!isServiceAuth) {
+                // Not a service-to-service request — pass through for normal auth guards
+                req.isServiceRequest = false;
+                return next();
+            }
+            const headers = this.normalizeHeaders(req.headers);
+            const servicePayload = this.interServiceAuthService.validateServiceAuth(headers);
+            req.serviceAuth = servicePayload;
+            req.isServiceRequest = true;
+            this.logger.debug(`Service-to-service call authenticated: ${servicePayload.serviceId} -> ${req.path}`);
+            next();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const stack = error instanceof Error ? error.stack : undefined;
+            this.logger.error(`Service authentication failed: ${message}`, stack);
+            if (error instanceof common_1.UnauthorizedException) {
+                return res.status(401).json({
+                    statusCode: 401,
+                    message: 'Service authentication failed',
+                    error: 'Unauthorized',
+                    timestamp: new Date().toISOString(),
+                    path: req.url,
+                });
+            }
+            return res.status(500).json({
+                statusCode: 500,
+                message: 'Internal server error during service authentication',
+                error: 'Internal Server Error',
+                timestamp: new Date().toISOString(),
+                path: req.url,
+            });
+        }
+    }
+    normalizeHeaders(headers) {
+        const normalized = {};
+        Object.keys(headers).forEach((key) => {
+            const value = headers[key];
+            if (typeof value === 'string') {
+                normalized[key.toLowerCase()] = value;
+            }
+            else if (Array.isArray(value) && value.length > 0) {
+                normalized[key.toLowerCase()] = value[0];
+            }
+        });
+        return normalized;
+    }
+};
+exports.InterServiceAuthMiddleware = InterServiceAuthMiddleware;
+exports.InterServiceAuthMiddleware = InterServiceAuthMiddleware = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [inter_service_auth_service_1.InterServiceAuthService])
+], InterServiceAuthMiddleware);

package/dist/inter-service-auth/inter-service-auth.module.d.ts

@@ -0,0 +1,11 @@
+import { DynamicModule } from '@nestjs/common';
+import { IServiceAuthConfig } from './inter-service-auth.config.interface';
+export declare class InterServiceAuthModule {
+    static forRoot(config: IServiceAuthConfig): DynamicModule;
+    static forRootAsync(options: {
+        imports?: any[];
+        useFactory: (...args: any[]) => IServiceAuthConfig | Promise<IServiceAuthConfig>;
+        inject?: any[];
+    }): DynamicModule;
+}
+//# sourceMappingURL=inter-service-auth.module.d.ts.map

package/dist/inter-service-auth/inter-service-auth.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-service-auth.module.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/inter-service-auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,qBAEa,sBAAsB;IACjC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa;IAWzD,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE;QAC3B,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;QAChB,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACjF,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC;KAChB,GAAG,aAAa;CAelB"}

package/dist/inter-service-auth/inter-service-auth.module.js

@@ -0,0 +1,44 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var InterServiceAuthModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterServiceAuthModule = void 0;
+const common_1 = require("@nestjs/common");
+const inter_service_auth_service_1 = require("./inter-service-auth.service");
+let InterServiceAuthModule = InterServiceAuthModule_1 = class InterServiceAuthModule {
+    static forRoot(config) {
+        return {
+            module: InterServiceAuthModule_1,
+            providers: [
+                { provide: inter_service_auth_service_1.INTER_SERVICE_AUTH_CONFIG, useValue: config },
+                inter_service_auth_service_1.InterServiceAuthService,
+            ],
+            exports: [inter_service_auth_service_1.InterServiceAuthService],
+        };
+    }
+    static forRootAsync(options) {
+        return {
+            module: InterServiceAuthModule_1,
+            imports: options.imports || [],
+            providers: [
+                {
+                    provide: inter_service_auth_service_1.INTER_SERVICE_AUTH_CONFIG,
+                    useFactory: options.useFactory,
+                    inject: options.inject || [],
+                },
+                inter_service_auth_service_1.InterServiceAuthService,
+            ],
+            exports: [inter_service_auth_service_1.InterServiceAuthService],
+        };
+    }
+};
+exports.InterServiceAuthModule = InterServiceAuthModule;
+exports.InterServiceAuthModule = InterServiceAuthModule = InterServiceAuthModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], InterServiceAuthModule);

package/dist/inter-service-auth/inter-service-auth.service.d.ts

@@ -0,0 +1,23 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { IServiceAuthConfig } from './inter-service-auth.config.interface';
+import { IServiceAuthPayload, IServiceCredentials } from './inter-service-auth.types';
+export declare const INTER_SERVICE_AUTH_CONFIG = "INTER_SERVICE_AUTH_CONFIG";
+export declare class InterServiceAuthService implements OnModuleDestroy {
+    private readonly config;
+    private readonly logger;
+    private readonly seenNonces;
+    private readonly intervalId;
+    constructor(config: IServiceAuthConfig);
+    onModuleDestroy(): void;
+    generateAuthHeaders(serviceId: string, targetSchema?: string): Record<string, string>;
+    validateServiceAuth(headers: Record<string, string>): IServiceAuthPayload;
+    getServiceConfig(serviceId: string): IServiceCredentials | undefined;
+    getConfiguredServices(): string[];
+    hasPermission(serviceId: string, permission: string): boolean;
+    hasRole(serviceId: string, role: string): boolean;
+    private purgeExpiredNonces;
+    private generateSignature;
+    private verifySignature;
+    private generateNonce;
+}
+//# sourceMappingURL=inter-service-auth.service.d.ts.map

package/dist/inter-service-auth/inter-service-auth.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-service-auth.service.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/inter-service-auth.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqD,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpG,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtF,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE,qBACa,uBAAwB,YAAW,eAAe;IASd,OAAO,CAAC,QAAQ,CAAC,MAAM;IARtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IAKnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;gBAEI,MAAM,EAAE,kBAAkB;IAK1F,eAAe,IAAI,IAAI;IAIvB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,GAAE,MAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA6BzF,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,mBAAmB;IA2EzE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIpE,qBAAqB,IAAI,MAAM,EAAE;IAIjC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAU7D,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAUjD,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,aAAa;CAGtB"}

package/dist/inter-service-auth/inter-service-auth.service.js

@@ -0,0 +1,202 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var InterServiceAuthService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterServiceAuthService = exports.INTER_SERVICE_AUTH_CONFIG = void 0;
+const common_1 = require("@nestjs/common");
+const crypto = __importStar(require("crypto"));
+exports.INTER_SERVICE_AUTH_CONFIG = 'INTER_SERVICE_AUTH_CONFIG';
+let InterServiceAuthService = InterServiceAuthService_1 = class InterServiceAuthService {
+    constructor(config) {
+        this.config = config;
+        this.logger = new common_1.Logger(InterServiceAuthService_1.name);
+        // Replay protection: tracks nonces seen within their validity window.
+        // Key: `${serviceId}:${nonce}`, value: expiresAt timestamp (ms).
+        // DEBT: in-memory only — assumes single-node deployment. For horizontal scaling, migrate to Redis.
+        this.seenNonces = new Map();
+        // Purge expired nonces every 60 s to prevent unbounded memory growth
+        this.intervalId = setInterval(() => this.purgeExpiredNonces(), 60_000);
+    }
+    onModuleDestroy() {
+        clearInterval(this.intervalId);
+    }
+    generateAuthHeaders(serviceId, targetSchema = '') {
+        const service = this.config.services[serviceId];
+        if (!service) {
+            throw new common_1.UnauthorizedException(`Service ${serviceId} not configured`);
+        }
+        const timestamp = Date.now();
+        const nonce = this.generateNonce();
+        const payload = {
+            serviceId: service.serviceId,
+            permissions: service.permissions ?? ['inter-service.communicate'],
+            roles: service.roles ?? ['service'],
+            timestamp,
+            nonce,
+        };
+        const signature = this.generateSignature(payload, service.secretKey, targetSchema);
+        return {
+            'X-Service-ID': service.serviceId,
+            'X-Service-API-Key': service.apiKey,
+            'X-Service-Timestamp': timestamp.toString(),
+            'X-Service-Nonce': nonce,
+            'X-Service-Signature': signature,
+            'X-Service-Auth': 'true',
+        };
+    }
+    validateServiceAuth(headers) {
+        const serviceId = headers['x-service-id'];
+        const apiKey = headers['x-service-api-key'];
+        const timestamp = parseInt(headers['x-service-timestamp'] || '0');
+        const nonce = headers['x-service-nonce'];
+        const signature = headers['x-service-signature'];
+        const isServiceAuth = headers['x-service-auth'] === 'true';
+        if (!isServiceAuth) {
+            throw new common_1.UnauthorizedException('Not a service-to-service request');
+        }
+        if (!serviceId || !apiKey || !timestamp || !nonce || !signature) {
+            throw new common_1.UnauthorizedException('Missing service authentication headers');
+        }
+        const service = Object.values(this.config.services).find((s) => s.serviceId === serviceId && s.apiKey === apiKey);
+        if (!service) {
+            this.logger.warn(`Unknown service attempted authentication: ${serviceId}`);
+            throw new common_1.UnauthorizedException('Invalid service credentials');
+        }
+        // signatureExpireMinutes: window looking backward — how long a signature remains valid.
+        // allowedTimeDriftSeconds: window looking forward — tolerance for sender clock skew.
+        // These are distinct concepts. Using Math.abs() with OR collapses both into min(expiry, drift),
+        // making the effective window only 30 s in both directions instead of 5 min back / 30 s forward.
+        const now = Date.now();
+        const maxAge = (this.config.signatureExpireMinutes ?? 5) * 60 * 1000;
+        const timeDrift = (this.config.allowedTimeDriftSeconds ?? 30) * 1000;
+        const ageMs = now - timestamp; // positive = timestamp is in the past; negative = timestamp is in the future
+        if (ageMs > maxAge) {
+            this.logger.warn(`Service auth signature expired: ${serviceId}`);
+            throw new common_1.UnauthorizedException('Service authentication signature expired');
+        }
+        if (ageMs < -timeDrift) {
+            this.logger.warn(`Service auth timestamp too far in the future: ${serviceId}`);
+            throw new common_1.UnauthorizedException('Service authentication timestamp invalid');
+        }
+        const payload = {
+            serviceId,
+            permissions: service.permissions ?? ['inter-service.communicate'],
+            roles: service.roles ?? ['service'],
+            timestamp,
+            nonce,
+        };
+        const targetSchema = headers['x-target-schema'] || '';
+        const expectedSignature = this.generateSignature(payload, service.secretKey, targetSchema);
+        if (!this.verifySignature(signature, expectedSignature)) {
+            this.logger.warn(`Invalid signature for service: ${serviceId}`);
+            throw new common_1.UnauthorizedException('Invalid service signature');
+        }
+        // Replay protection: reject any nonce already seen within its validity window.
+        // DEBT: in-memory only — assumes single-node deployment. For horizontal scaling, migrate to Redis.
+        const nonceKey = `${serviceId}:${nonce}`;
+        if (this.seenNonces.has(nonceKey)) {
+            this.logger.warn(`Replayed nonce detected for service: ${serviceId}`);
+            throw new common_1.UnauthorizedException('Nonce already used');
+        }
+        this.seenNonces.set(nonceKey, timestamp + maxAge);
+        if (this.config.enableLogging) {
+            this.logger.log(`Service authenticated successfully: ${serviceId}`);
+        }
+        return payload;
+    }
+    getServiceConfig(serviceId) {
+        return this.config.services[serviceId];
+    }
+    getConfiguredServices() {
+        return Object.keys(this.config.services);
+    }
+    hasPermission(serviceId, permission) {
+        const service = this.config.services[serviceId];
+        if (!service)
+            return false;
+        return ((service.permissions ?? []).includes(permission) ||
+            (service.permissions ?? []).includes('*') ||
+            (service.permissions ?? []).includes('inter-service.*'));
+    }
+    hasRole(serviceId, role) {
+        const service = this.config.services[serviceId];
+        if (!service)
+            return false;
+        const roles = service.roles ?? ['service'];
+        // Every configured service implicitly carries the base 'service' role,
+        // regardless of explicit configuration. This enables coarse-grained checks
+        // like @RequireServiceRoles('service') to pass for any valid credential.
+        return roles.includes(role) || role === 'service';
+    }
+    purgeExpiredNonces() {
+        const now = Date.now();
+        for (const [key, expiresAt] of this.seenNonces) {
+            if (expiresAt < now) {
+                this.seenNonces.delete(key);
+            }
+        }
+    }
+    generateSignature(payload, secretKey, targetSchema = '') {
+        const data = `${payload.serviceId}:${payload.timestamp}:${payload.nonce}:${targetSchema}`;
+        return crypto.createHmac('sha256', secretKey).update(data).digest('hex');
+    }
+    verifySignature(provided, expected) {
+        if (provided.length !== expected.length) {
+            return false;
+        }
+        return crypto.timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex'));
+    }
+    generateNonce() {
+        return crypto.randomBytes(16).toString('hex');
+    }
+};
+exports.InterServiceAuthService = InterServiceAuthService;
+exports.InterServiceAuthService = InterServiceAuthService = InterServiceAuthService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(exports.INTER_SERVICE_AUTH_CONFIG)),
+    __metadata("design:paramtypes", [Object])
+], InterServiceAuthService);

package/dist/inter-service-auth/inter-service-auth.types.d.ts

@@ -0,0 +1,57 @@
+import { Request } from 'express';
+export interface IServiceCredentials {
+    serviceId: string;
+    apiKey: string;
+    secretKey: string;
+    /** Default: ['inter-service.communicate'] */
+    permissions?: string[];
+    /** Default: ['service'] */
+    roles?: string[];
+}
+export interface IServiceAuthPayload {
+    serviceId: string;
+    permissions: string[];
+    roles: string[];
+    timestamp: number;
+    nonce: string;
+}
+export interface IServiceAuthRequest {
+    serviceId: string;
+    timestamp: number;
+    nonce: string;
+    signature: string;
+}
+export declare const SERVICE_NAMES: {
+    readonly AUTH: "contractx-authorizations";
+    readonly CONTRACTS: "contractx-contracts";
+    readonly PROVIDERS: "contractx-providers";
+    readonly DELIVERIES: "contractx-deliveries";
+    readonly INVOICES: "contractx-invoices";
+    readonly WORKFLOWS: "contractx-workflows";
+    readonly SLAS: "contractx-SLAs";
+    readonly MEETINGS: "contractx-meetings";
+    readonly NOTIFICATIONS: "contractx-notifications";
+    readonly AUDIT: "contractx-audit";
+};
+export type ServiceName = (typeof SERVICE_NAMES)[keyof typeof SERVICE_NAMES];
+declare module 'express-serve-static-core' {
+    interface Request {
+        serviceAuth?: IServiceAuthPayload;
+        isServiceRequest?: boolean;
+    }
+}
+/**
+ * Narrowed Request type for handlers that sit behind ServiceAuthGuard.
+ * Cast to this type when you need non-optional access to serviceAuth:
+ *
+ *   @Get()
+ *   @UseGuards(ServiceAuthGuard)
+ *   myEndpoint(@Req() req: AuthenticatedServiceRequest) {
+ *     const { serviceId } = req.serviceAuth; // guaranteed non-null
+ *   }
+ */
+export type AuthenticatedServiceRequest = Request & {
+    serviceAuth: IServiceAuthPayload;
+    isServiceRequest: true;
+};
+//# sourceMappingURL=inter-service-auth.types.d.ts.map

package/dist/inter-service-auth/inter-service-auth.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter-service-auth.types.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/inter-service-auth.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;CAWhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAI7E,OAAO,QAAQ,2BAA2B,CAAC;IACzC,UAAU,OAAO;QACf,WAAW,CAAC,EAAE,mBAAmB,CAAC;QAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG;IAClD,WAAW,EAAE,mBAAmB,CAAC;IACjC,gBAAgB,EAAE,IAAI,CAAC;CACxB,CAAC"}

package/dist/inter-service-auth/inter-service-auth.types.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_NAMES = void 0;
+exports.SERVICE_NAMES = {
+    AUTH: 'contractx-authorizations',
+    CONTRACTS: 'contractx-contracts',
+    PROVIDERS: 'contractx-providers',
+    DELIVERIES: 'contractx-deliveries',
+    INVOICES: 'contractx-invoices',
+    WORKFLOWS: 'contractx-workflows',
+    SLAS: 'contractx-SLAs',
+    MEETINGS: 'contractx-meetings',
+    NOTIFICATIONS: 'contractx-notifications',
+    AUDIT: 'contractx-audit',
+};

package/dist/inter-service-auth/service-auth.decorators.d.ts

@@ -0,0 +1,12 @@
+/** Requires the caller to have all listed permissions in their service credentials. */
+export declare const RequireServicePermissions: (...permissions: string[]) => import("@nestjs/common").CustomDecorator<string>;
+/** Requires the caller to have at least one of the listed roles. */
+export declare const RequireServiceRoles: (...roles: string[]) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Controls whether M2M requests are accepted on this endpoint.
+ * @AllowServiceAuth(false) blocks M2M even when @RequireServiceAuth() is set at class level.
+ */
+export declare const AllowServiceAuth: (allow?: boolean) => import("@nestjs/common").CustomDecorator<string>;
+/** Marks this endpoint as M2M-only. Rejects any request without valid service credentials. */
+export declare const RequireServiceAuth: () => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=service-auth.decorators.d.ts.map

package/dist/inter-service-auth/service-auth.decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-auth.decorators.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/service-auth.decorators.ts"],"names":[],"mappings":"AAQA,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,GAAI,GAAG,aAAa,MAAM,EAAE,qDACf,CAAC;AAEpD,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,MAAM,EAAE,qDAA0C,CAAC;AAEjG;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAO,OAAc,qDAA+C,CAAC;AAEtG,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,wDAAoD,CAAC"}

package/dist/inter-service-auth/service-auth.decorators.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireServiceAuth = exports.AllowServiceAuth = exports.RequireServiceRoles = exports.RequireServicePermissions = void 0;
+const common_1 = require("@nestjs/common");
+const service_auth_guard_1 = require("./service-auth.guard");
+/** Requires the caller to have all listed permissions in their service credentials. */
+const RequireServicePermissions = (...permissions) => (0, common_1.SetMetadata)(service_auth_guard_1.SERVICE_PERMISSIONS_KEY, permissions);
+exports.RequireServicePermissions = RequireServicePermissions;
+/** Requires the caller to have at least one of the listed roles. */
+const RequireServiceRoles = (...roles) => (0, common_1.SetMetadata)(service_auth_guard_1.SERVICE_ROLES_KEY, roles);
+exports.RequireServiceRoles = RequireServiceRoles;
+/**
+ * Controls whether M2M requests are accepted on this endpoint.
+ * @AllowServiceAuth(false) blocks M2M even when @RequireServiceAuth() is set at class level.
+ */
+const AllowServiceAuth = (allow = true) => (0, common_1.SetMetadata)(service_auth_guard_1.ALLOW_SERVICE_AUTH_KEY, allow);
+exports.AllowServiceAuth = AllowServiceAuth;
+/** Marks this endpoint as M2M-only. Rejects any request without valid service credentials. */
+const RequireServiceAuth = () => (0, common_1.SetMetadata)(service_auth_guard_1.REQUIRE_SERVICE_AUTH_KEY, true);
+exports.RequireServiceAuth = RequireServiceAuth;
+// TODO: @CurrentService() param decorator postponed — implement cleanly with
+// createParamDecorator if a handler needs the calling serviceId.

package/dist/inter-service-auth/service-auth.guard.d.ts

@@ -0,0 +1,17 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { InterServiceAuthService } from './inter-service-auth.service';
+export declare const SERVICE_PERMISSIONS_KEY = "service_permissions";
+export declare const SERVICE_ROLES_KEY = "service_roles";
+export declare const ALLOW_SERVICE_AUTH_KEY = "allow_service_auth";
+export declare const REQUIRE_SERVICE_AUTH_KEY = "require_service_auth";
+export declare class ServiceAuthGuard implements CanActivate {
+    private readonly reflector;
+    private readonly interServiceAuthService;
+    private readonly logger;
+    constructor(reflector: Reflector, interServiceAuthService: InterServiceAuthService);
+    canActivate(context: ExecutionContext): boolean;
+    private checkPermission;
+    private checkRole;
+}
+//# sourceMappingURL=service-auth.guard.d.ts.map

package/dist/inter-service-auth/service-auth.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-auth.guard.d.ts","sourceRoot":"","sources":["../../src/inter-service-auth/service-auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAIjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAC7D,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAC3D,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAK/D,qBACa,gBAAiB,YAAW,WAAW;IAIhD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IAJ1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGtC,SAAS,EAAE,SAAS,EACpB,uBAAuB,EAAE,uBAAuB;IAGnE,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;IA6E/C,OAAO,CAAC,eAAe;IAyBvB,OAAO,CAAC,SAAS;CAYlB"}

package/dist/inter-service-auth/service-auth.guard.js

@@ -0,0 +1,121 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceAuthGuard = exports.REQUIRE_SERVICE_AUTH_KEY = exports.ALLOW_SERVICE_AUTH_KEY = exports.SERVICE_ROLES_KEY = exports.SERVICE_PERMISSIONS_KEY = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const inter_service_auth_service_1 = require("./inter-service-auth.service");
+// Exported so decorators and consumers can reference keys without magic strings
+exports.SERVICE_PERMISSIONS_KEY = 'service_permissions';
+exports.SERVICE_ROLES_KEY = 'service_roles';
+exports.ALLOW_SERVICE_AUTH_KEY = 'allow_service_auth';
+exports.REQUIRE_SERVICE_AUTH_KEY = 'require_service_auth';
+// TODO: @CurrentService() param decorator postponed — implement cleanly with
+// createParamDecorator if a handler needs the calling serviceId.
+let ServiceAuthGuard = class ServiceAuthGuard {
+    constructor(reflector, interServiceAuthService) {
+        this.reflector = reflector;
+        this.interServiceAuthService = interServiceAuthService;
+        this.logger = new common_1.Logger('ServiceAuthGuard');
+    }
+    canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        // Step 1: if @RequireServiceAuth() is set, reject non-M2M requests immediately
+        const requireServiceAuth = this.reflector.getAllAndOverride(exports.REQUIRE_SERVICE_AUTH_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (requireServiceAuth === true) {
+            if (!request.isServiceRequest || !request.serviceAuth) {
+                this.logger.warn(`Service authentication required but not provided for ${request.method} ${request.path}`);
+                throw new common_1.UnauthorizedException('Service-to-service authentication required');
+            }
+        }
+        else {
+            // No service auth requirement — let other guards handle non-M2M requests
+            if (!request.isServiceRequest || !request.serviceAuth) {
+                return true;
+            }
+        }
+        // Step 2: @AllowServiceAuth(false) explicitly blocks M2M on this endpoint.
+        // This wins even when @RequireServiceAuth() is set at class level.
+        const allowServiceAuth = this.reflector.getAllAndOverride(exports.ALLOW_SERVICE_AUTH_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (allowServiceAuth === false) {
+            throw new common_1.ForbiddenException('Service authentication not allowed for this endpoint');
+        }
+        const serviceAuth = request.serviceAuth;
+        // Step 3: permission check (handler metadata takes precedence over class via getAllAndOverride)
+        const requiredPermissions = this.reflector.getAllAndOverride(exports.SERVICE_PERMISSIONS_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]) || [];
+        if (requiredPermissions.length > 0) {
+            const hasPermission = requiredPermissions.some((permission) => this.checkPermission(serviceAuth.serviceId, serviceAuth.permissions, permission));
+            if (!hasPermission) {
+                this.logger.warn(`Service ${serviceAuth.serviceId} lacks required permissions: ${requiredPermissions.join(', ')}`);
+                throw new common_1.ForbiddenException('Insufficient permissions for service operation');
+            }
+        }
+        // Step 4: role check
+        const requiredRoles = this.reflector.getAllAndOverride(exports.SERVICE_ROLES_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]) || [];
+        if (requiredRoles.length > 0) {
+            const hasRole = requiredRoles.some((role) => this.checkRole(serviceAuth.serviceId, serviceAuth.roles, role));
+            if (!hasRole) {
+                this.logger.warn(`Service ${serviceAuth.serviceId} lacks required roles: ${requiredRoles.join(', ')}`);
+                throw new common_1.ForbiddenException('Insufficient role for service operation');
+            }
+        }
+        this.logger.debug(`Service ${serviceAuth.serviceId} authorized for ${request.method} ${request.path}`);
+        return true;
+    }
+    checkPermission(serviceId, servicePermissions, requiredPermission) {
+        if (servicePermissions.includes('*') || servicePermissions.includes('inter-service.*')) {
+            return true;
+        }
+        if (servicePermissions.includes(requiredPermission)) {
+            return true;
+        }
+        // Prefix wildcard: 'contracts.*' covers 'contracts.read', 'contracts.write', etc.
+        const hasWildcardPermission = servicePermissions.some((permission) => {
+            if (permission.endsWith('.*')) {
+                const basePermission = permission.slice(0, -2);
+                return requiredPermission.startsWith(basePermission);
+            }
+            return false;
+        });
+        if (hasWildcardPermission) {
+            return true;
+        }
+        return this.interServiceAuthService.hasPermission(serviceId, requiredPermission);
+    }
+    checkRole(serviceId, serviceRoles, requiredRole) {
+        if (serviceRoles.includes(requiredRole)) {
+            return true;
+        }
+        // Any service with the base 'service' role passes coarse-grained role checks
+        if (serviceRoles.includes('service')) {
+            return true;
+        }
+        return this.interServiceAuthService.hasRole(serviceId, requiredRole);
+    }
+};
+exports.ServiceAuthGuard = ServiceAuthGuard;
+exports.ServiceAuthGuard = ServiceAuthGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        inter_service_auth_service_1.InterServiceAuthService])
+], ServiceAuthGuard);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "permissions-contractx",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Enterprise-grade authentication and authorization package for NestJS microservices with role-based and permission-based access control",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",