@mbc-cqrs-serverless/core 1.3.3 → 1.3.5

package/README.md

@@ -215,6 +215,43 @@ export class TodoDataSyncHandler implements IDataSyncHandler {
 }
 ```
 
+## Group-based roles
+
+`RolesGuard` checks direct roles from JWT `custom:roles` first, then roles from groups in `custom:groups` (tenant-scoped). Group → role mappings are **not** stored in the JWT; implement a resolver in your app.
+
+**JWT example:**
+
+```json
+{
+  "custom:roles": "[{\"tenant\":\"tenant-a\",\"role\":\"admin\"}]",
+  "custom:groups": "[{\"tenant\":\"tenant-a\",\"groups\":[\"sales-team\"]}]"
+}
+```
+
+**Resolver (one per app):**
+
+```typescript
+import {
+  GroupRoleResolver,
+  IGroupRoleResolver,
+} from '@mbc-cqrs-serverless/core';
+
+// Do not add @Injectable() — @GroupRoleResolver() already registers the provider.
+@GroupRoleResolver()
+export class AppGroupRoleResolver implements IGroupRoleResolver {
+  async resolveRoles({ tenantCode, groupIds, claims }) {
+    // Load roles from DynamoDB, RDS, config, etc.
+    return ['viewer', 'reporter'];
+  }
+}
+```
+
+Register the class in your NestJS module `providers`. `AuthModule` is imported automatically via core `AppModule.forRoot()` and exports `GroupRoleResolverRegistry` globally for `@Auth()` / `RolesGuard`.
+
+### Extending authorization
+
+`RolesGuard` evaluates `tenantRoles` from the JWT (not `getUserRole()`). The protected `getUserRole()` method is **deprecated** and not called by the default guard. Subclasses should override `verifyRole` or `resolveGroupRoles` for custom logic.
+
 ## Environment Variables
 
 | Variable | Description | Default |

package/dist/app.module.js

@@ -13,6 +13,7 @@ const core_1 = require("@nestjs/core");
 const app_controller_1 = require("./app.controller");
 const app_module_definition_1 = require("./app.module-definition");
 const app_service_1 = require("./app.service");
+const auth_1 = require("./auth");
 const data_sync_module_1 = require("./command-events/data-sync.module");
 const data_store_module_1 = require("./data-store/data-store.module");
 const env_validation_1 = require("./env.validation");
@@ -64,6 +65,7 @@ exports.AppModule = AppModule;
 exports.AppModule = AppModule = __decorate([
     (0, common_1.Module)({
         imports: [
+            auth_1.AuthModule,
             notification_module_1.NotificationModule,
             data_store_module_1.DataStoreModule,
             data_sync_module_1.DataSyncModule,

package/dist/app.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAsD;AACtD,2CAA6C;AAC7C,uCAAmD;AAEnD,qDAAgD;AAChD,mEAA+E;AAC/E,+CAA0C;AAC1C,wEAAkE;AAClE,sEAAgE;AAChE,qDAAoD;AACpD,qCAAsC;AACtC,6EAAwE;AACxE,uDAAkD;AAClD,kEAA6D;AAC7D,2EAAqE;AAa9D,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,+CAAuB;IACpD,MAAM,CAAC,OAAO,CAAC,OAA4B;QACzC,MAAM,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,MAAM,CAAA;QAC5E,MAAM,OAAO,GAAW;YACtB;gBACE,IAAI,EAAE,KAAK;gBACX,MAAM,EAAE,OAAO,CAAC,UAAU;aAC3B;SACF,CAAA;QACD,iCAAiC;QACjC,IAAI,uBAAuB,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,oBAAW;aACpB,CAAC,CAAA;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;QAC3C,OAAO,CAAC,IAAI,CACV,qBAAY,CAAC,OAAO,CAAC;YACnB,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,IAAI;YACX,eAAe,EAAE,IAAI;YACrB,iBAAiB,EAAE;gBACjB,YAAY,EAAE,KAAK;gBACnB,UAAU,EAAE,IAAI;aACjB;YACD,QAAQ,EAAE,IAAA,kCAAiB,EAAC,OAAO,CAAC,MAAM,CAAC;SAC5C,CAAC,CACH,CAAA;QACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QAChC,IAAI,uBAAuB,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,oBAAW,CAAC,CAAA;QAC3B,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,mBAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;QAE5C,OAAO;YACL,GAAG,MAAM;YACT,OAAO;SACR,CAAA;IACH,CAAC;CACF,CAAA;AA1CY,8BAAS;oBAAT,SAAS;IAXrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE;YACP,wCAAkB;YAClB,mCAAe;YACf,iCAAc;YACd,yCAAkB;YAClB,0BAAW;SACZ;QACD,WAAW,EAAE,CAAC,8BAAa,CAAC;QAC5B,SAAS,EAAE,CAAC,wBAAU,EAAE,kCAAe,CAAC;KACzC,CAAC;GACW,SAAS,CA0CrB"}
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAsD;AACtD,2CAA6C;AAC7C,uCAAmD;AAEnD,qDAAgD;AAChD,mEAA+E;AAC/E,+CAA0C;AAC1C,iCAAmC;AACnC,wEAAkE;AAClE,sEAAgE;AAChE,qDAAoD;AACpD,qCAAsC;AACtC,6EAAwE;AACxE,uDAAkD;AAClD,kEAA6D;AAC7D,2EAAqE;AAc9D,IAAM,SAAS,GAAf,MAAM,SAAU,SAAQ,+CAAuB;IACpD,MAAM,CAAC,OAAO,CAAC,OAA4B;QACzC,MAAM,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,MAAM,CAAA;QAC5E,MAAM,OAAO,GAAW;YACtB;gBACE,IAAI,EAAE,KAAK;gBACX,MAAM,EAAE,OAAO,CAAC,UAAU;aAC3B;SACF,CAAA;QACD,iCAAiC;QACjC,IAAI,uBAAuB,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,oBAAW;aACpB,CAAC,CAAA;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACrC,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;QAC3C,OAAO,CAAC,IAAI,CACV,qBAAY,CAAC,OAAO,CAAC;YACnB,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,IAAI;YACX,eAAe,EAAE,IAAI;YACrB,iBAAiB,EAAE;gBACjB,YAAY,EAAE,KAAK;gBACnB,UAAU,EAAE,IAAI;aACjB;YACD,QAAQ,EAAE,IAAA,kCAAiB,EAAC,OAAO,CAAC,MAAM,CAAC;SAC5C,CAAC,CACH,CAAA;QACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QAChC,IAAI,uBAAuB,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,oBAAW,CAAC,CAAA;QAC3B,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,mBAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;QAE5C,OAAO;YACL,GAAG,MAAM;YACT,OAAO;SACR,CAAA;IACH,CAAC;CACF,CAAA;AA1CY,8BAAS;oBAAT,SAAS;IAZrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE;YACP,iBAAU;YACV,wCAAkB;YAClB,mCAAe;YACf,iCAAc;YACd,yCAAkB;YAClB,0BAAW;SACZ;QACD,WAAW,EAAE,CAAC,8BAAa,CAAC;QAC5B,SAAS,EAAE,CAAC,wBAAU,EAAE,kCAAe,CAAC;KACzC,CAAC;GACW,SAAS,CA0CrB"}

package/dist/auth/auth.module.d.ts

@@ -0,0 +1,2 @@
+export declare class AuthModule {
+}

package/dist/auth/auth.module.js

@@ -0,0 +1,30 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthModule = void 0;
+const common_1 = require("@nestjs/common");
+const roles_guard_1 = require("../guard/roles.guard");
+const explorer_service_1 = require("../services/explorer.service");
+const authz_bootstrap_service_1 = require("./authz-bootstrap.service");
+const group_role_resolver_registry_1 = require("./group-role-resolver.registry");
+let AuthModule = class AuthModule {
+};
+exports.AuthModule = AuthModule;
+exports.AuthModule = AuthModule = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({
+        providers: [
+            explorer_service_1.ExplorerService,
+            group_role_resolver_registry_1.GroupRoleResolverRegistry,
+            authz_bootstrap_service_1.AuthzBootstrapService,
+            roles_guard_1.RolesGuard,
+        ],
+        exports: [group_role_resolver_registry_1.GroupRoleResolverRegistry, roles_guard_1.RolesGuard, explorer_service_1.ExplorerService],
+    })
+], AuthModule);
+//# sourceMappingURL=auth.module.js.map

package/dist/auth/auth.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.module.js","sourceRoot":"","sources":["../../src/auth/auth.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA+C;AAE/C,sDAAiD;AACjD,mEAA8D;AAC9D,uEAAiE;AACjE,iFAA0E;AAYnE,IAAM,UAAU,GAAhB,MAAM,UAAU;CAAG,CAAA;AAAb,gCAAU;qBAAV,UAAU;IAVtB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACN,SAAS,EAAE;YACT,kCAAe;YACf,wDAAyB;YACzB,+CAAqB;YACrB,wBAAU;SACX;QACD,OAAO,EAAE,CAAC,wDAAyB,EAAE,wBAAU,EAAE,kCAAe,CAAC;KAClE,CAAC;GACW,UAAU,CAAG"}

package/dist/auth/authz-bootstrap.service.d.ts

@@ -0,0 +1,11 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { ExplorerService } from '../services/explorer.service';
+import { GroupRoleResolverRegistry } from './group-role-resolver.registry';
+export declare class AuthzBootstrapService implements OnApplicationBootstrap {
+    private readonly explorerService;
+    private readonly moduleRef;
+    private readonly registry;
+    constructor(explorerService: ExplorerService, moduleRef: ModuleRef, registry: GroupRoleResolverRegistry);
+    onApplicationBootstrap(): void;
+}

package/dist/auth/authz-bootstrap.service.js

@@ -0,0 +1,47 @@
+"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.AuthzBootstrapService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const explorer_service_1 = require("../services/explorer.service");
+const group_role_resolver_registry_1 = require("./group-role-resolver.registry");
+let AuthzBootstrapService = class AuthzBootstrapService {
+    constructor(explorerService, moduleRef, registry) {
+        this.explorerService = explorerService;
+        this.moduleRef = moduleRef;
+        this.registry = registry;
+    }
+    onApplicationBootstrap() {
+        const types = this.explorerService.exploreGroupRoleResolvers();
+        if (types.length > 1) {
+            throw new Error('Only one @GroupRoleResolver() is allowed per application');
+        }
+        if (types.length === 0) {
+            return;
+        }
+        const instance = this.moduleRef.get(types[0], {
+            strict: false,
+        });
+        if (!instance) {
+            throw new Error(`GroupRoleResolver ${types[0].name} was discovered but could not be resolved from DI`);
+        }
+        this.registry.set(instance);
+    }
+};
+exports.AuthzBootstrapService = AuthzBootstrapService;
+exports.AuthzBootstrapService = AuthzBootstrapService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [explorer_service_1.ExplorerService,
+        core_1.ModuleRef,
+        group_role_resolver_registry_1.GroupRoleResolverRegistry])
+], AuthzBootstrapService);
+//# sourceMappingURL=authz-bootstrap.service.js.map

package/dist/auth/authz-bootstrap.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-bootstrap.service.js","sourceRoot":"","sources":["../../src/auth/authz-bootstrap.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAmE;AACnE,uCAAwC;AAExC,mEAA8D;AAE9D,iFAA0E;AAGnE,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAChC,YACmB,eAAgC,EAChC,SAAoB,EACpB,QAAmC;QAFnC,oBAAe,GAAf,eAAe,CAAiB;QAChC,cAAS,GAAT,SAAS,CAAW;QACpB,aAAQ,GAAR,QAAQ,CAA2B;IACnD,CAAC;IAEJ,sBAAsB;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC,yBAAyB,EAAE,CAAA;QAE9D,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAA;QACH,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAM;QACR,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAqB,KAAK,CAAC,CAAC,CAAC,EAAE;YAChE,MAAM,EAAE,KAAK;SACd,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,qBAAqB,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,mDAAmD,CACtF,CAAA;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;CACF,CAAA;AAhCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;qCAGyB,kCAAe;QACrB,gBAAS;QACV,wDAAyB;GAJ3C,qBAAqB,CAgCjC"}

package/dist/auth/group-role-resolver.interface.d.ts

@@ -0,0 +1,13 @@
+import { JwtClaims } from '../context/invoke';
+export interface TenantGroupMembership {
+    tenant: string;
+    groups: string[];
+}
+export interface ResolveGroupRolesInput {
+    tenantCode: string;
+    groupIds: string[];
+    claims?: JwtClaims;
+}
+export interface IGroupRoleResolver {
+    resolveRoles(input: ResolveGroupRolesInput): Promise<string[]>;
+}

package/dist/auth/group-role-resolver.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=group-role-resolver.interface.js.map

package/dist/auth/group-role-resolver.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-role-resolver.interface.js","sourceRoot":"","sources":["../../src/auth/group-role-resolver.interface.ts"],"names":[],"mappings":""}

package/dist/auth/group-role-resolver.registry.d.ts

@@ -0,0 +1,6 @@
+import { IGroupRoleResolver } from './group-role-resolver.interface';
+export declare class GroupRoleResolverRegistry {
+    private resolver?;
+    set(resolver: IGroupRoleResolver): void;
+    get(): IGroupRoleResolver | undefined;
+}

package/dist/auth/group-role-resolver.registry.js

@@ -0,0 +1,26 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupRoleResolverRegistry = void 0;
+const common_1 = require("@nestjs/common");
+let GroupRoleResolverRegistry = class GroupRoleResolverRegistry {
+    set(resolver) {
+        if (this.resolver) {
+            throw new Error('Only one @GroupRoleResolver() is allowed per application');
+        }
+        this.resolver = resolver;
+    }
+    get() {
+        return this.resolver;
+    }
+};
+exports.GroupRoleResolverRegistry = GroupRoleResolverRegistry;
+exports.GroupRoleResolverRegistry = GroupRoleResolverRegistry = __decorate([
+    (0, common_1.Injectable)()
+], GroupRoleResolverRegistry);
+//# sourceMappingURL=group-role-resolver.registry.js.map

package/dist/auth/group-role-resolver.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-role-resolver.registry.js","sourceRoot":"","sources":["../../src/auth/group-role-resolver.registry.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA2C;AAKpC,IAAM,yBAAyB,GAA/B,MAAM,yBAAyB;IAGpC,GAAG,CAAC,QAA4B;QAC9B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,0DAA0D,CAC3D,CAAA;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;CACF,CAAA;AAfY,8DAAyB;oCAAzB,yBAAyB;IADrC,IAAA,mBAAU,GAAE;GACA,yBAAyB,CAerC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,4 @@
+export * from './auth.module';
+export * from './authz-bootstrap.service';
+export * from './group-role-resolver.interface';
+export * from './group-role-resolver.registry';

package/dist/auth/index.js

@@ -0,0 +1,21 @@
+"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 });
+__exportStar(require("./auth.module"), exports);
+__exportStar(require("./authz-bootstrap.service"), exports);
+__exportStar(require("./group-role-resolver.interface"), exports);
+__exportStar(require("./group-role-resolver.registry"), exports);
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA6B;AAC7B,4DAAyC;AACzC,kEAA+C;AAC/C,iEAA8C"}

package/dist/command-events/data-sync.new.event.handler.js

@@ -34,7 +34,31 @@ let DataSyncNewCommandEventHandler = DataSyncNewCommandEventHandler_1 = class Da
             .replace('@', '-v')
             .replace(/[^0-9A-Za-z_-]+/g, `__${Math.random().toString(36).substring(2, 4)}__`);
         const sfnExecName = `${moduleName}-${ddbRecordId}-${Date.now()}`;
-        return await this.sfnService.startExecution(this.sfnArn, event, sfnExecName);
+        try {
+            return await this.sfnService.startExecution(this.sfnArn, event, sfnExecName);
+        }
+        catch (error) {
+            // Only tolerate a missing state machine when running under
+            // serverless-offline (local development), where DynamoDB Streams can fire
+            // before Step Functions Local has registered the state machine.
+            // serverless-offline sets IS_OFFLINE and it is never set in a deployed
+            // Lambda, so it is a reliable local-only signal (same check as
+            // EmailService). SFN_ENDPOINT is NOT used here because it is a generic
+            // endpoint override that may legitimately be set in production (VPC
+            // endpoint, PrivateLink). In any other environment a missing state
+            // machine is a real misconfiguration (wrong ARN, undeployed/deleted state
+            // machine, deploy race) and must surface as a failure — otherwise the
+            // command is silently written without its data-sync ever running, with no
+            // Lambda error metric / stream retry / alarm to detect it.
+            const isOffline = process.env.IS_OFFLINE === 'true' || process.env.IS_OFFLINE === '1';
+            if (error?.name === 'StateMachineDoesNotExist' && isOffline) {
+                this.logger.warn(`State machine not found (ARN: ${this.sfnArn}). ` +
+                    'This may happen during local development if the state machine is not yet registered. ' +
+                    `Skipping execution for: ${sfnExecName}`);
+                return;
+            }
+            throw error;
+        }
     }
 };
 exports.DataSyncNewCommandEventHandler = DataSyncNewCommandEventHandler;

package/dist/command-events/data-sync.new.event.handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-sync.new.event.handler.js","sourceRoot":"","sources":["../../src/command-events/data-sync.new.event.handler.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAuC;AACvC,2CAA8C;AAE9C,8CAA+C;AAC/C,8CAA4C;AAE5C,8EAAwE;AACxE,+DAA+D;AAGxD,IAAM,8BAA8B,sCAApC,MAAM,8BAA8B;IAMzC,YACmB,MAAqB,EACrB,UAA+B,EAC/B,eAAgC;QAFhC,WAAM,GAAN,MAAM,CAAe;QACrB,eAAU,GAAV,UAAU,CAAqB;QAC/B,oBAAe,GAAf,eAAe,CAAiB;QANlC,WAAM,GAAG,IAAI,eAAM,CAAC,gCAA8B,CAAC,IAAI,CAAC,CAAA;QAQvE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;IAC7C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAA8B;QAC1C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACtE,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAA;QACpC,MAAM,WAAW,GAAG,GAAG,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE;aACpE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;aACpB,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC;aAClB,OAAO,CACN,kBAAkB,EAClB,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CACpD,CAAA;QAEH,MAAM,WAAW,GAAG,GAAG,UAAU,IAAI,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;QAChE,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,CAAA;IAC9E,CAAC;CACF,CAAA;AA7BY,wEAA8B;yCAA9B,8BAA8B;IAD1C,IAAA,yBAAY,EAAC,6CAAuB,CAAC;qCAQT,sBAAa;QACT,2CAAmB;QACd,4BAAe;GATxC,8BAA8B,CA6B1C"}
+{"version":3,"file":"data-sync.new.event.handler.js","sourceRoot":"","sources":["../../src/command-events/data-sync.new.event.handler.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAuC;AACvC,2CAA8C;AAE9C,8CAA+C;AAC/C,8CAA4C;AAE5C,8EAAwE;AACxE,+DAA+D;AAGxD,IAAM,8BAA8B,sCAApC,MAAM,8BAA8B;IAMzC,YACmB,MAAqB,EACrB,UAA+B,EAC/B,eAAgC;QAFhC,WAAM,GAAN,MAAM,CAAe;QACrB,eAAU,GAAV,UAAU,CAAqB;QAC/B,oBAAe,GAAf,eAAe,CAAiB;QANlC,WAAM,GAAG,IAAI,eAAM,CAAC,gCAA8B,CAAC,IAAI,CAAC,CAAA;QAQvE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;IAC7C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAA8B;QAC1C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAA;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACtE,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAA;QACpC,MAAM,WAAW,GAAG,GAAG,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE;aACpE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;aACpB,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC;aAClB,OAAO,CACN,kBAAkB,EAClB,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CACpD,CAAA;QAEH,MAAM,WAAW,GAAG,GAAG,UAAU,IAAI,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;QAChE,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,CACzC,IAAI,CAAC,MAAM,EACX,KAAK,EACL,WAAW,CACZ,CAAA;QACH,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,2DAA2D;YAC3D,0EAA0E;YAC1E,gEAAgE;YAChE,uEAAuE;YACvE,+DAA+D;YAC/D,uEAAuE;YACvE,oEAAoE;YACpE,mEAAmE;YACnE,0EAA0E;YAC1E,sEAAsE;YACtE,0EAA0E;YAC1E,2DAA2D;YAC3D,MAAM,SAAS,GACb,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,GAAG,CAAA;YACrE,IAAI,KAAK,EAAE,IAAI,KAAK,0BAA0B,IAAI,SAAS,EAAE,CAAC;gBAC5D,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,iCAAiC,IAAI,CAAC,MAAM,KAAK;oBAC/C,uFAAuF;oBACvF,2BAA2B,WAAW,EAAE,CAC3C,CAAA;gBACD,OAAM;YACR,CAAC;YACD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;CACF,CAAA;AA3DY,wEAA8B;yCAA9B,8BAA8B;IAD1C,IAAA,yBAAY,EAAC,6CAAuB,CAAC;qCAQT,sBAAa;QACT,2CAAmB;QACd,4BAAe;GATxC,8BAA8B,CA2D1C"}

package/dist/commands/command.event.handler.d.ts

@@ -1,7 +1,7 @@
 import { ConfigService } from '@nestjs/config';
 import { DataSyncCommandSfnEvent, StepFunctionStateInput } from '../command-events/data-sync.sfn.event';
 import { S3Service } from '../data-store';
-import { CommandModuleOptions } from '../interfaces';
+import { CommandModel, CommandModuleOptions, DetailKey } from '../interfaces';
 import { SnsService } from '../queue';
 import { StepFunctionService } from '../step-func/step-function.service';
 import { CommandService } from './command.service';
@@ -22,11 +22,36 @@ export declare class CommandEventHandler {
     execute(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput | StepFunctionStateInput[]>;
     protected handleStepState(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput | StepFunctionStateInput[]>;
     protected waitConfirmToken(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
+    /**
+     * Retry wrapper around commandService.getItem for the cross-execution
+     * predecessor-status check in waitConfirmToken. Bounded and short —
+     * smooths a single transient DDB failure; does not wait out an outage.
+     */
+    protected getItemWithRetry(key: DetailKey, options: {
+        consistentRead: boolean;
+    }, maxAttempts: number, baseDelayMs: number): Promise<CommandModel>;
+    /**
+     * Bounded retry with exponential backoff (baseDelayMs * 2^(attempt - 1)),
+     * rethrowing the last error once every attempt is exhausted. Shared by both
+     * sides of the version handshake so the pull path (waitConfirmToken) and the
+     * push path (checkNextToken) tolerate transient DynamoDB failures equally.
+     */
+    protected withRetry<T>(fn: () => Promise<T>, maxAttempts: number, baseDelayMs: number): Promise<T>;
     protected checkVersion(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
     protected setTtlCommand(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
     protected historyCopy(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
     protected transformData(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput[]>;
     protected syncData(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
     protected checkNextToken(event: DataSyncCommandSfnEvent): Promise<StepFunctionStateInput>;
+    protected handleResumeExecutionError(event: DataSyncCommandSfnEvent, e: unknown, options: {
+        benignNames: ReadonlySet<string>;
+        logContext: string;
+        alarmPayload: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Best-effort alarm publish — SNS failure must not fail the SFN step
+     * (e.g. after updateTaskToken already succeeded).
+     */
+    protected publishAlarmSafely(event: DataSyncCommandSfnEvent, errorDetails: any): Promise<void>;
     protected publishAlarm(event: DataSyncCommandSfnEvent, errorDetails: any): Promise<void>;
 }

package/dist/commands/command.event.handler.js

@@ -49,7 +49,7 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
         }
         catch (error) {
             await this.commandService.updateStatus(event.commandKey, (0, status_enum_1.getCommandStatus)(event.stepStateName, status_enum_1.CommandStatus.STATUS_FAILED), event.commandRecord.requestId);
-            await this.publishAlarm(event, error.stack);
+            await this.publishAlarmSafely(event, error.stack);
             throw error;
         }
     }
@@ -76,12 +76,101 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
     async waitConfirmToken(event) {
         this.logger.debug('waitConfirmToken::', event);
         await this.commandService.updateTaskToken(event.commandKey, event.taskToken);
+        if (event.commandRecord.version > 1) {
+            const prevSk = (0, key_1.addSortKeyVersion)((0, key_1.removeSortKeyVersion)(event.commandRecord.sk), event.commandRecord.version - 1);
+            let prevCommand;
+            let prevReadFailed = false;
+            try {
+                // consistentRead: true — predecessor status across independent SFN
+                // executions must not be a stale eventually-consistent read.
+                //
+                // Bounded retry (3 attempts, exponential backoff baseDelayMs * 2^(n-1)):
+                // best-effort check — updateTaskToken already succeeded; checkNextToken
+                // on the predecessor remains the primary resume path.
+                prevCommand = await this.getItemWithRetry({ pk: event.commandRecord.pk, sk: prevSk }, { consistentRead: true }, 3, 100);
+            }
+            catch (e) {
+                // After app + SDK retries, treat as persistent degradation of the
+                // self-resume backstop — do not fail the step (token already stored).
+                prevReadFailed = true;
+                this.logger.error(`[${event.commandKey.pk}] Could not read predecessor status for command v${event.commandRecord.version} after retries, self-resume backstop degraded: ` +
+                    `${e instanceof Error ? e.message : 'Unknown error'}`, e instanceof Error ? e.stack : undefined);
+                await this.publishAlarmSafely(event, {
+                    self_resume_predecessor_read_failed: true,
+                    cause: e instanceof Error ? e.message : String(e),
+                });
+            }
+            // A successful read that returns no row is not the same as "predecessor
+            // has not reached finish yet" — the command chain is append-only, so for
+            // version > 1 the predecessor row must exist. Surface it instead of
+            // letting it fall through the same silent path as normal waiting.
+            if (!prevReadFailed && !prevCommand) {
+                this.logger.warn(`[${event.commandKey.pk}] Predecessor command v${event.commandRecord.version - 1} not found (sk: ${prevSk}) — ` +
+                    `self-resume backstop cannot evaluate predecessor status`);
+            }
+            // Limitation: self-resume only when predecessor status is finish:STARTED
+            // or finish:FINISHED. Any predecessor exit before FINISH (wait_prev_command
+            // 24h timeout Pass→Fail with no Lambda/DDB update, version-mismatch fail,
+            // or *:FAILED mid-pipeline) leaves a non-finish status (often with a stale
+            // taskToken), so this check will not self-resume and this version may wait
+            // out its own 24h timeout (cascade).
+            const finishStarted = (0, status_enum_1.getCommandStatus)(sfn_name_enum_1.DataSyncCommandSfnName.FINISH, status_enum_1.CommandStatus.STATUS_STARTED);
+            const finishFinished = (0, status_enum_1.getCommandStatus)(sfn_name_enum_1.DataSyncCommandSfnName.FINISH, status_enum_1.CommandStatus.STATUS_FINISHED);
+            const prevEnteredFinish = prevCommand?.status === finishStarted ||
+                prevCommand?.status === finishFinished;
+            if (prevEnteredFinish) {
+                this.logger.log(`[${event.commandKey.pk}] Prev command already in finish step — self-resuming v${event.commandRecord.version}`);
+                try {
+                    await this.sfnService.resumeExecution(event.taskToken, {
+                        result: 'resumed_by_prev_version',
+                        prevVersion: event.commandRecord.version - 1,
+                    });
+                }
+                catch (e) {
+                    await this.handleResumeExecutionError(event, e, {
+                        benignNames: new Set(['TaskDoesNotExist', 'TaskTimedOut']),
+                        logContext: `[${event.commandKey.pk}] Self-resume for v${event.commandRecord.version}`,
+                        alarmPayload: { self_resume_failed: true },
+                    });
+                }
+            }
+        }
         return {
             result: {
                 token: event.taskToken,
             },
         };
     }
+    /**
+     * Retry wrapper around commandService.getItem for the cross-execution
+     * predecessor-status check in waitConfirmToken. Bounded and short —
+     * smooths a single transient DDB failure; does not wait out an outage.
+     */
+    async getItemWithRetry(key, options, maxAttempts, baseDelayMs) {
+        return await this.withRetry(() => this.commandService.getItem(key, options), maxAttempts, baseDelayMs);
+    }
+    /**
+     * Bounded retry with exponential backoff (baseDelayMs * 2^(attempt - 1)),
+     * rethrowing the last error once every attempt is exhausted. Shared by both
+     * sides of the version handshake so the pull path (waitConfirmToken) and the
+     * push path (checkNextToken) tolerate transient DynamoDB failures equally.
+     */
+    async withRetry(fn, maxAttempts, baseDelayMs) {
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                lastError = e;
+                if (attempt < maxAttempts) {
+                    const delayMs = baseDelayMs * Math.pow(2, attempt - 1);
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+        throw lastError;
+    }
     async checkVersion(event) {
         this.logger.debug('Checking version::', event.commandRecord);
         const sk = (0, key_1.removeSortKeyVersion)(event.commandRecord.sk);
@@ -92,10 +181,16 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
         this.logger.debug('Checking version for data::', data);
         const commandVersion = event.commandRecord.version;
         const nextVersion = 1 + (data?.version || 0);
+        // consistentRead: true — the predecessor row is written by an independent
+        // SFN execution. A stale eventually-consistent miss makes oldCommand look
+        // absent, which returns result: 0 and routes straight to set_ttl_command,
+        // skipping wait_prev_command and letting a later version's sync_data land
+        // out of order. Matches the predecessor reads in waitConfirmToken and
+        // getNextCommand.
         const oldCommand = await this.commandService.getItem({
             pk: event.commandRecord.pk,
             sk: (0, key_1.addSortKeyVersion)(sk, commandVersion - 1),
-        });
+        }, { consistentRead: true });
         if (nextVersion === commandVersion) {
             return {
                 result: 0,
@@ -117,7 +212,7 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
             error: 'version is not match',
             cause: 'next version must be ' + nextVersion + ' but got ' + commandVersion,
         };
-        await this.publishAlarm(event, errorDetails);
+        await this.publishAlarmSafely(event, errorDetails);
         return errorDetails;
     }
     async setTtlCommand(event) {
@@ -142,7 +237,12 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
     }
     async transformData(event) {
         this.logger.debug('transformData:: ', event.commandRecord);
-        return this.commandService.dataSyncHandlers.map((cls) => ({
+        const handlers = this.commandService.dataSyncHandlers;
+        if (handlers.length === 0) {
+            this.logger.warn(`[${this.options.tableName}] transformData: no DataSyncHandlers registered — ` +
+                `no sync will occur for ${this.options.tableName}`);
+        }
+        return handlers.map((cls) => ({
             prevStateName: event.stepStateName,
             result: cls.constructor.name,
         }));
@@ -162,7 +262,31 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
     }
     async checkNextToken(event) {
         this.logger.debug('checkNextToken:: ', event.commandRecord);
-        const nextCommand = await this.commandService.getNextCommand(event.commandKey);
+        let nextCommand;
+        try {
+            // Same bounded retry as the pull-side predecessor read in
+            // waitConfirmToken — without it a transient DDB failure here takes out
+            // both halves of the handshake at once.
+            nextCommand = await this.withRetry(() => this.commandService.getNextCommand(event.commandKey), 3, 100);
+        }
+        catch (e) {
+            // Deliberately does not rethrow. Failing this step makes execute() write
+            // finish:FAILED, and the successor's self-resume backstop only reacts to
+            // finish:STARTED|FINISHED — so the push path and the pull path would
+            // collapse together and the chain would stall until the 24h timeout.
+            // Returning normally lets execute() write finish:FINISHED, keeping the
+            // successor's self-resume armed for its own token-store pass. The step is
+            // reported as finished even though the push resume never ran; the alarm
+            // below is what records that, and the successor is the recovery path.
+            this.logger.error(`[${event.commandKey.pk}] Could not read next command after retries, ` +
+                `push resume skipped (successor self-resume remains armed): ` +
+                `${e instanceof Error ? e.message : 'Unknown error'}`, e instanceof Error ? e.stack : undefined);
+            await this.publishAlarmSafely(event, {
+                next_command_read_failed: true,
+                cause: e instanceof Error ? e.message : String(e),
+            });
+            return null;
+        }
         if (!nextCommand) {
             this.logger.debug('No next command version found. Chain ends.');
             return null;
@@ -176,7 +300,15 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
                 });
             }
             catch (e) {
-                this.logger.warn(`Could not resume command v${nextCommand.version}: ${e instanceof Error ? e.message : 'Unknown error'}`);
+                await this.handleResumeExecutionError(event, e, {
+                    benignNames: new Set(['TaskDoesNotExist']),
+                    logContext: `[${event.commandKey.pk}] Resume for v${nextCommand.version} (sk: ${nextCommand.sk})`,
+                    alarmPayload: {
+                        push_resume_failed: true,
+                        nextVersion: nextCommand.version,
+                        nextSk: nextCommand.sk,
+                    },
+                });
             }
         }
         else {
@@ -184,6 +316,33 @@ let CommandEventHandler = CommandEventHandler_1 = class CommandEventHandler {
         }
         return null;
     }
+    async handleResumeExecutionError(event, e, options) {
+        const name = e instanceof Error ? e.name : undefined;
+        if (name && options.benignNames.has(name)) {
+            this.logger.warn(`${options.logContext} already consumed (${name})`);
+            return;
+        }
+        this.logger.error(`${options.logContext} failed unexpectedly (${name ?? 'unknown'}): ` +
+            `${e instanceof Error ? e.message : 'Unknown error'}`, e instanceof Error ? e.stack : undefined);
+        await this.publishAlarmSafely(event, {
+            ...options.alarmPayload,
+            errorName: name ?? 'unknown',
+            cause: e instanceof Error ? e.message : String(e),
+        });
+    }
+    /**
+     * Best-effort alarm publish — SNS failure must not fail the SFN step
+     * (e.g. after updateTaskToken already succeeded).
+     */
+    async publishAlarmSafely(event, errorDetails) {
+        try {
+            await this.publishAlarm(event, errorDetails);
+        }
+        catch (alarmError) {
+            this.logger.error(`[${event.commandKey.pk}] publishAlarm failed: ` +
+                `${alarmError instanceof Error ? alarmError.message : 'Unknown error'}`, alarmError instanceof Error ? alarmError.stack : undefined);
+        }
+    }
     async publishAlarm(event, errorDetails) {
         this.logger.debug('event', event);
         const alarm = {