Changelog
All notable changes to MBC CQRS Serverless are documented here. This project follows Semantic Versioning and Conventional Commits.
Version Scheme
x.y.z- Production releasesx.y.z-beta.n- Beta releases for testingx.y.z-alpha.n- Alpha releases for early access
Stable Releases (1.x)
1.8.0 (2026-11-15)
Breaking Changes
- master: Key segments are now validated for every application. A setting code, the
settingCodeandcodeof master data, and theuserIdandgroupIdof group and user settings must be non-empty and must not contain#or@, and a setting code must not beMASTER_SETTING. Otherwise every create, upsert and bulk request,getSetting(GET /api/master-setting/:code) andMasterDataService.list(GET /api/master-data) return 400. Updates and deletes by key (PATCH/DELETE /api/master-setting/:pk/:sk,PUT/DELETE /api/master-data/:pk/:sk) also reject a sort key that contains@. Rows already stored with@in their key are therefore no longer reachable through the API and must be re-created under a valid key (See Details) (PR #518)- In 1.7.0, core cut a sort key at its last
@, the version separator. A value with one@, such as an e-mail address used as auserIdor code, was silently stored under a truncated, different key, and a code with two or more@(for exampleX@Y@Z) could store a row whose key still contains@(MASTER_SETTING#X@Y). Rows whose key contains@can no longer be read, updated or deleted through the API. Find them (a sort key containing@in the DynamoDB data table or the RDS master table) and re-create them under a valid key - A
#in a code built the key of another row, such as a user's personal setting. Master data rows already stored with#in theircodestay readable and can still be updated or deleted by key, but a create or upsert that sends such a code is rejected. Check integrations that generate codes, user IDs or group IDs with#or@before upgrading
- In 1.7.0, core cut a sort key at its last
- master: Setting rows and data rows are now changed only through their own routes.
PUT/DELETE /api/master-data/:pk/:sk(MasterDataService.update/delete) reject aMASTER_SETTING#...key, andPATCH/DELETE /api/master-setting/:pk/:sk(MasterSettingService.updateSetting/deleteSetting) reject a key that is notMASTER_SETTING#followed by a code. Group and user keys such asMASTER_SETTING#USER#u1#S1are still accepted (See Details) (PR #518) - master: Master copy is restricted to system administrators. With
controllerAuthset,POST /api/master-setting/copyrequires thesystem_adminrole from thecustom:rolesclaim; roles incontrollerAuth.writeand group-derived roles do not allow it. With an access resolver registered,MasterSettingService.copyalso requires a write grant whosesystemIdandsettingCodeare both*(See Details) (PR #518) - master:
POST /api/master-bulknow upserts the settings first and the data rows after, instead of both at once, so data rows can use a setting created in the same request. The keys of every item are validated before the first write, but the request is not atomic across settings and data: with an access resolver registered, the access checks of the data items run after the settings are written, so a forbidden data item fails the request and leaves the settings written (See Details) (PR #518) - master:
GET /api/tasks/sfn-task-parentnow resolves the tenant like the rest of the framework: thecustom:tenantclaim wins over thex-tenant-codeheader. It used to read acustom:tenant_codeclaim that nobody sets, so it always took the tenant from the header (PR #518)
Features
- master: Add the opt-in
controllerAuthmodule option, which guards the built-in master routes. Reads need a role inread(default: any logged-in user), writes need a role inwrite(default:system_admin), and the requested tenant must be the caller's tenant unless the request only reads the common tenant or the caller has a cross-tenant role. Without it the routes stay unguarded and the module logs a startup warning (See Details) (PR #518) - master: Scope master data per system. A master setting can carry a
systemId(stored in lower case;sharedis reserved for data every system receives), and its data rows inherit it. Register one class with@MasterAccessResolver()to grant read and write per system and per setting. The services then check the grants in every method, and the list endpoints filter in the SQL query, so pagination and totals stay correct (See Details) (PR #518) - master: Add
GET /api/master-access, which tells a UI whether access control is enabled and returns the caller's grants, andMasterSettingService.assignSystem, which tags existing untagged rows of a setting code with asystemId(See Details) (PR #518) - master: Add
includeCommonto the master setting and master data list searches. It adds the common tenant's rows whose code the caller's tenant does not have (See Details) (PR #518) - master: Add the
commonTenantCodemodule option (the tenant that holds common master data, defaultcommon) and theenableCopyTaskmodule option (registers the master copy handler, default: the value ofenableController) (See Details) (PR #518) - master: Add a nullable
system_idcolumn to the RDS master table of the project template, written by the template's RDS handler, and returnsystemIdat the top level of API responses (See Details) (PR #518) - master, survey-template: Add the
databaseProvidermodule option (postgresqlormysql). By default it is detected from the Prisma client (See Details) (PR #518)
Bug Fixes
- master: Master copy now reads data from the source setting's tenant. It used to read from a hard-coded
meltectenant (PR #518) - master: Master copy now copies sequences. Both keys used to be built from the target tenant, so nothing was ever copied. A target sequence behind the source jumps to the source's value; the write is conditional, so a target that issued numbers in the meantime is never moved back (PR #518)
- master, survey-template: Name, code and keyword searches failed on MySQL, the default database of
mbc new, because they always sent the PostgreSQL-onlymode: 'insensitive'. The setting description search used a JSON path that fit neither database; it now uses['description']on PostgreSQL and'$.description'on MySQL (See Details) (PR #518) - master: A setting update that omits
settingValueno longer clears the setting's attributes, one that omitsnamekeeps the name, and a master data update that omitsseqkeeps it (PR #518)
Upgrade Notes
- For an application that sets neither
controllerAuthnor a resolver, the other changes are: a__systemIdkey sent by a client inattributesis always removed; responses go throughtoPublicRow, so a row stored earlier with a client-planted__systemIdreturns it as a top-levelsystemId;GET /api/master-accessis added when the controllers are enabled; and the DTOs acceptsystemIdandincludeCommon, which are ignored without a resolver - New projects get an empty
controllerAuthobject insrc/master/master.module.ts, so master writes needsystem_adminuntil roles are configured. Existing projects are not changed - With a resolver registered, read methods called without
invokeContextare denied. Server-side code must passinvokeContext, orskipAccessCheck: truefor trusted internal work - Applications generated earlier must add a nullable
system_idcolumn and writesystemId: getSystemId(cmd)in their own RDS handler before registering a resolver, becauseupdate-scheme.tsdoes not change an existing schema or handler. With a resolver registered, the application refuses to start if the PrismaMastermodel has nosystemIdfield - With a resolver registered, creating a tenant-level override of a common setting that has no
systemIdtreats that setting asshared: a requestedsystemIdother thansharedis rejected with 400, write access tosharedis required, and the override stores nosystemId includeCommonis bounded. A master data list withincludeCommonrequiressettingCodeunless the caller is in the common tenant, and a tenant holding more than 10,000 matching rows gets a 400 instead of a database error; results are not truncated. A settings list withincludeCommondoes not merge the common tenant's group and user setting rows- With
registerAsync, the staticcommonTenantCode,databaseProviderandcontrollerAuthoptions override the values the factory returns, even when the static value is undefined, so pass them statically - List searches now work on MySQL, so applications that patched
mode: 'insensitive'out of the dist files (for example withpatch-package) can drop the patch. SetdatabaseProviderif a startup warning says the database could not be detected - With
controllerAuth, a caller whose token has nocustom:tenantclaim and who names the common tenant inx-tenant-codemay get 403 whencommonTenantCodeis not listed in theCOMMON_TENANT_CODESenvironment variable, because the tenant-override check of the base guard reads that variable. Keep the two in sync - See Migration Guide v1.8.0 for upgrade instructions.
Documentation
- master: Add the framework guide Master data access control and per-system sync, which covers the resolver, the rollout order on the hub and publishing changes to SNS per system (PR #518)
1.7.0 (2026-11-09)
Features
- core: Add the protected
CommandService.getCommandAdmissionConditionshook for atomic command admission. ACommandServicesubclass can return DynamoDBConditionCheckentries, which are committed with the initial command write in a singleTransactWriteItemsrequest. A command is then accepted only if, for example, a maintenance gate is still open at the generation the request observed, which closes the race between a preflight gate check and a gate that closes in the meantime. The default returns no checks and keeps the plainPutItempath, so existing apps behave as before (See Details) (PR #515)- The hook runs for
publishSync,publishAsync, the partial update methods andduplicate, immediately before the initial command is written. An update that changes nothing still returns without calling the hook
- The hook runs for
- core: Add
CommandAdmissionRejectedException(HTTP 409) for a failed admission check andCommandAdmissionContentionException(HTTP 503) for a transaction cancelled byTransactionConflict. A version conflict on the command write is still reported asConditionalCheckFailedException(409), and any other cancellation is rethrown as the originalTransactionCanceledException(500). Core does not retry (See Details) (PR #515) - cli: The infrastructure template now grants
dynamodb:ConditionCheckItemon the stack-prefixed DynamoDB tables, which the admission transaction needs on witness tables (See Details) (PR #515)
Upgrade Notes
- No code changes are needed unless you override the new hook. Unit tests that run a real
CommandServicewith a hand-writtenDynamoDbServicemock that only definesputItemmust also mockputItemWithConditions, becauseCommandServicenow writes every initial command through it (See Details)- With a
createMockauto-mock from@golevelup/ts-jest, the test does not throw, butputItemis never reached becauseputItemWithConditionsis auto-mocked, so assertions onputItemfail without an obvious reason. Assert onputItemWithConditionsinstead, or stub it to callputItem. A spy on theputItemof a realDynamoDbServicekeeps working, becauseputItemWithConditionsdelegates toputItemwhen there are no conditions (PR #516)
- With a
- Using the hook requires
dynamodb:ConditionCheckItemon every witness table. Projects generated from an earlier CLI template must add it by hand - Every item in a transaction consumes double write capacity, even when the transaction is cancelled. Concurrent commands that check the same witness item can cancel each other with
TransactionConflict. This contention has not been measured on the DynamoDB service and DynamoDB Local does not reproduce it, so load test the expected concurrency in a real environment - See Migration Guide v1.7.0 for upgrade instructions.
1.6.0 (2026-11-03)
Breaking Changes
- all packages: Require Node.js 22 or later (
engines.nodeis now>=22). Node.js 18 and 20 are end of life and will not receive the fix for CVE-2026-111497 (Node2Shell), a remote code execution vulnerability in the Brotli decoder bundled with Node.js. The fix ships in Node.js 22.23.4, 24.22.1 and 26.12.1.@mbc-cqrs-serverless/corealso now depends on nodemailer 10, which itself requires Node.js 20 or later. CI tests Node.js 22 and 24 (See Details) (PR #512)- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
npm installreportsEBADENGINE, and fails whenengine-strictis enabled
- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
- core: nodemailer 10 ships its own type definitions, and its default export is no longer a namespace. Code that uses
nodemailer.SendMailOptions,nodemailer.Transporterornodemailer.SentMessageInfomust import these types by name fromnodemailerinstead, and@types/nodemailershould be removed. Apps that only useEmailServiceneed no code changes (See Details) (PR #512) - cli: New projects use Node.js 22. The Lambda function and layer use
NODEJS_22_X, the Docker image is based onnode:22-bookworm-slimand installsopenssl(Prisma's query engine needs libssl, which bookworm-slim does not ship), theinfra-localimages usenode:22-alpine, andserverless.ymlusesnodejs22.xwith serverless-offline^13.9.0. The CDK pipeline pins Node.js 22 for its CodeBuild projects, and@types/nodemoves to 22 (See Details) (PR #512)- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
opensslin the image
- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
Security
- Clear high and critical advisories in production dependencies: proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0, multer 2.5.0, nodemailer 10.3.1, @modelcontextprotocol/sdk 1.32.2, zod 4.6.7 (PR #512)
- The CLI project template's dependency overrides now also pin proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0 and multer 2.5.0, so newly scaffolded projects no longer ship these advisories. The
qsoverride, in the framework and the template, moves to^6.16.1, the minimum that the patched body-parser and express 5 require (PR #512)
Documentation
- mcp-server: Add the v1.5.0 → v1.6.0 migration guide (Node.js 22, nodemailer 10 types) to the
mbc-migrateskill and add Node.js 22 to its compatibility matrix (PR #512)
1.5.0 (2026-09-24)
Breaking Changes
- cli: Replace LocalStack with Floci (
floci/floci:1.6.0) as the local S3 emulator in the scaffolded local development stack. LocalStack Community Edition reached end of life in March 2026. Floci serves S3 on the same port (4566) with path-style addressing, so application code and.envvalues do not change, and deployed environments are not affected (See Details) (PR #503)- Existing projects: replace the
localstackservice ininfra-local/docker-compose.yml, removeserverless-localstack, and add a bucket CORS rule so presigned upload/view URLs keep working in the browser
- Existing projects: replace the
Features
- directory:
DirectoryServicemethods now takeICommandOptionsinstead of an options type that only allowedinvokeContext, so callers can passsourceandrequestIdthrough to the command for tracing. Backward compatible:invokeContextis still the only required field (PR #505)
Bug Fixes
- cli: Fix
mbc newfailing at dependency installation withEOVERRIDE: Override for js-yaml@^4.1.0 conflicts with direct dependency(broken since v1.3.5). The template'sjs-yamloverride now references the direct dependency, which moves to^4.3.2and also clears a high-severityjs-yamladvisory (PR #508) - cli: Fix
npm run migratein newly scaffolded projects. Prisma does not expand the:-default syntax used forLOCAL_RDS_PORTinDATABASE_URL(P1013), andprisma/ddb.tsdid not expand the endpoint variables at all (Invalid URL). Existing projects can apply the same fix: referenceLOCAL_RDS_PORTwithout a:-default inDATABASE_URL, and load.envinprisma/ddb.tswithexpand(dotenv.config())fromdotenv-expand(PR #508) - mcp-server: Ship the Claude Code skills in the published npm package. They were missing from the package, so
mbc install-skillsand the manualcp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/*step could not find them (See Details) (PR #506)
Documentation
- mcp-server: Add the v1.4.0 → v1.5.0 migration guide (LocalStack → Floci, bucket CORS) to the
mbc-migrateskill and update the Floci commands in thembc-debugskill (PR #506)
1.4.0 (2026-08-02)
Features
- core, master, directory, survey-template, ui-setting: Make the DynamoDB table names of the domain modules configurable via a backward-compatible
tableName?option, and addregisterAsyncsupport to all four modules. Defaults are unchanged (master/directory/survey/master), so existing apps upgrade with no code changes (See Details) (PR #493)DirectoryStorageModuleadditionally acceptspkPrefix?(defaultDIRECTORY) andprismaModelName?(defaultdirectory)- The
directory→documentrename (PR #469) is now expressed as opt-in configuration (tableName: 'document',pkPrefix: 'DOCUMENT',prismaModelName: 'document') rather than a forced default
Changes
- master, directory, survey-template:
prismaServiceis now always required at registration (previously validated only whenenableController: true). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. PassprismaServiceexplicitly if you registered withenableController: falseand relied on a globally-provided token - master, ui-setting: When
MasterModuleandSettingModuleshare the defaultmastertable, the framework logs a startup warning if both own themaster_CommandEventHandleralias (data-sync ownership becomes import-order dependent). SetregisterEventHandlerAlias: falseonSettingModulesoMasterModuleowns the alias - master:
MasterModulelogs a warning if itstableNameis overridden — themastertable is a framework-wide config store read at a fixedmaster-dataname byTtlServiceand the sequence package, so renaming it is not fully supported
1.3.5 (2026-08-01)
Bug Fixes
- core: Harden command-handler resume against read-after-write races —
waitConfirmTokennow self-resumes when the predecessor command has already finished, closes the residual TOCTOU window viaSTARTED|FINISHEDstatus checks, retries the predecessorgetItemwith exponential backoff, and classifiescheckNextTokenresume failures so a stuck resume raises an alarm instead of failing silently (PR #465) - core: Add
ConsistentReadsupport toDynamoDbService.getItemand thread it throughCommandService.getItem/getNextCommand, so resume decisions read the latest committed state instead of a possibly stale replica (PR #465) - cli: Fix the scaffolded infra template failing
cdk synth/deploy— the import-CSV Step Functions definition referenced an undefinedaws_stepfunctionsidentifier (corrected tocdk.aws_stepfunctions), which broke every project scaffolded withmbc newon v1.3.4. Upgrade to v1.3.5 to restore deployability (PR #465)
Features
- infra: Add CloudWatch alarms on the command-handler Step Functions state machine (
ExecutionsFailedand degraded self-resume paths), add a 24h timeout and catch onwait_prev_command, and scope theSendTaskSuccessIAM permission to the command state machine ARN (PR #465) - cli: Local development tooling for
mbc newprojects — make the local infra ports configurable viaLOCAL_*_PORTenv vars (defaults unchanged), keep cognito-local's JWT issuer in sync withLOCAL_COGNITO_PORT, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps (PR #337)
Security
- Restore the blocking
npm audit --omit=dev --audit-level=highCI gate that was temporarily disabled, and patchbrace-expansion(top-levelbrace-expansion@2→5.0.8); root production audit: 0 critical/high (PR #482)- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
packages/cli/templates/infra) is not an npm workspace member and ships@aws/pdk(build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in issue #486
- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
1.3.4 (2026-07-17)
Bug Fixes
- core, cli: Lower the default
ATTRIBUTE_LIMIT_SIZEfrom389120(380 KB) to102400(100 KB) in CDK infra templates and env examples — the previous default was sized for DynamoDB's 400 KB item limit, but Step Functions enforces a 256 KB payload limit per state, and the command state machine passes the DynamoDB stream event twice (`input.--- sidebar_position: 100 sidebar_label: "Backend (Framework)" description: Track all notable changes, new features, and bug fixes in MBC CQRS Serverless releases.
Changelog
All notable changes to MBC CQRS Serverless are documented here. This project follows Semantic Versioning and Conventional Commits.
Version Scheme
x.y.z- Production releasesx.y.z-beta.n- Beta releases for testingx.y.z-alpha.n- Alpha releases for early access
Stable Releases (1.x)
1.8.0 (2026-11-15)
Breaking Changes
- master: Key segments are now validated for every application. A setting code, the
settingCodeandcodeof master data, and theuserIdandgroupIdof group and user settings must be non-empty and must not contain#or@, and a setting code must not beMASTER_SETTING. Otherwise every create, upsert and bulk request,getSetting(GET /api/master-setting/:code) andMasterDataService.list(GET /api/master-data) return 400. Updates and deletes by key (PATCH/DELETE /api/master-setting/:pk/:sk,PUT/DELETE /api/master-data/:pk/:sk) also reject a sort key that contains@. Rows already stored with@in their key are therefore no longer reachable through the API and must be re-created under a valid key (See Details) (PR #518)- In 1.7.0, core cut a sort key at its last
@, the version separator. A value with one@, such as an e-mail address used as auserIdor code, was silently stored under a truncated, different key, and a code with two or more@(for exampleX@Y@Z) could store a row whose key still contains@(MASTER_SETTING#X@Y). Rows whose key contains@can no longer be read, updated or deleted through the API. Find them (a sort key containing@in the DynamoDB data table or the RDS master table) and re-create them under a valid key - A
#in a code built the key of another row, such as a user's personal setting. Master data rows already stored with#in theircodestay readable and can still be updated or deleted by key, but a create or upsert that sends such a code is rejected. Check integrations that generate codes, user IDs or group IDs with#or@before upgrading
- In 1.7.0, core cut a sort key at its last
- master: Setting rows and data rows are now changed only through their own routes.
PUT/DELETE /api/master-data/:pk/:sk(MasterDataService.update/delete) reject aMASTER_SETTING#...key, andPATCH/DELETE /api/master-setting/:pk/:sk(MasterSettingService.updateSetting/deleteSetting) reject a key that is notMASTER_SETTING#followed by a code. Group and user keys such asMASTER_SETTING#USER#u1#S1are still accepted (See Details) (PR #518) - master: Master copy is restricted to system administrators. With
controllerAuthset,POST /api/master-setting/copyrequires thesystem_adminrole from thecustom:rolesclaim; roles incontrollerAuth.writeand group-derived roles do not allow it. With an access resolver registered,MasterSettingService.copyalso requires a write grant whosesystemIdandsettingCodeare both*(See Details) (PR #518) - master:
POST /api/master-bulknow upserts the settings first and the data rows after, instead of both at once, so data rows can use a setting created in the same request. The keys of every item are validated before the first write, but the request is not atomic across settings and data: with an access resolver registered, the access checks of the data items run after the settings are written, so a forbidden data item fails the request and leaves the settings written (See Details) (PR #518) - master:
GET /api/tasks/sfn-task-parentnow resolves the tenant like the rest of the framework: thecustom:tenantclaim wins over thex-tenant-codeheader. It used to read acustom:tenant_codeclaim that nobody sets, so it always took the tenant from the header (PR #518)
Features
- master: Add the opt-in
controllerAuthmodule option, which guards the built-in master routes. Reads need a role inread(default: any logged-in user), writes need a role inwrite(default:system_admin), and the requested tenant must be the caller's tenant unless the request only reads the common tenant or the caller has a cross-tenant role. Without it the routes stay unguarded and the module logs a startup warning (See Details) (PR #518) - master: Scope master data per system. A master setting can carry a
systemId(stored in lower case;sharedis reserved for data every system receives), and its data rows inherit it. Register one class with@MasterAccessResolver()to grant read and write per system and per setting. The services then check the grants in every method, and the list endpoints filter in the SQL query, so pagination and totals stay correct (See Details) (PR #518) - master: Add
GET /api/master-access, which tells a UI whether access control is enabled and returns the caller's grants, andMasterSettingService.assignSystem, which tags existing untagged rows of a setting code with asystemId(See Details) (PR #518) - master: Add
includeCommonto the master setting and master data list searches. It adds the common tenant's rows whose code the caller's tenant does not have (See Details) (PR #518) - master: Add the
commonTenantCodemodule option (the tenant that holds common master data, defaultcommon) and theenableCopyTaskmodule option (registers the master copy handler, default: the value ofenableController) (See Details) (PR #518) - master: Add a nullable
system_idcolumn to the RDS master table of the project template, written by the template's RDS handler, and returnsystemIdat the top level of API responses (See Details) (PR #518) - master, survey-template: Add the
databaseProvidermodule option (postgresqlormysql). By default it is detected from the Prisma client (See Details) (PR #518)
Bug Fixes
- master: Master copy now reads data from the source setting's tenant. It used to read from a hard-coded
meltectenant (PR #518) - master: Master copy now copies sequences. Both keys used to be built from the target tenant, so nothing was ever copied. A target sequence behind the source jumps to the source's value; the write is conditional, so a target that issued numbers in the meantime is never moved back (PR #518)
- master, survey-template: Name, code and keyword searches failed on MySQL, the default database of
mbc new, because they always sent the PostgreSQL-onlymode: 'insensitive'. The setting description search used a JSON path that fit neither database; it now uses['description']on PostgreSQL and'$.description'on MySQL (See Details) (PR #518) - master: A setting update that omits
settingValueno longer clears the setting's attributes, one that omitsnamekeeps the name, and a master data update that omitsseqkeeps it (PR #518)
Upgrade Notes
- For an application that sets neither
controllerAuthnor a resolver, the other changes are: a__systemIdkey sent by a client inattributesis always removed; responses go throughtoPublicRow, so a row stored earlier with a client-planted__systemIdreturns it as a top-levelsystemId;GET /api/master-accessis added when the controllers are enabled; and the DTOs acceptsystemIdandincludeCommon, which are ignored without a resolver - New projects get an empty
controllerAuthobject insrc/master/master.module.ts, so master writes needsystem_adminuntil roles are configured. Existing projects are not changed - With a resolver registered, read methods called without
invokeContextare denied. Server-side code must passinvokeContext, orskipAccessCheck: truefor trusted internal work - Applications generated earlier must add a nullable
system_idcolumn and writesystemId: getSystemId(cmd)in their own RDS handler before registering a resolver, becauseupdate-scheme.tsdoes not change an existing schema or handler. With a resolver registered, the application refuses to start if the PrismaMastermodel has nosystemIdfield - With a resolver registered, creating a tenant-level override of a common setting that has no
systemIdtreats that setting asshared: a requestedsystemIdother thansharedis rejected with 400, write access tosharedis required, and the override stores nosystemId includeCommonis bounded. A master data list withincludeCommonrequiressettingCodeunless the caller is in the common tenant, and a tenant holding more than 10,000 matching rows gets a 400 instead of a database error; results are not truncated. A settings list withincludeCommondoes not merge the common tenant's group and user setting rows- With
registerAsync, the staticcommonTenantCode,databaseProviderandcontrollerAuthoptions override the values the factory returns, even when the static value is undefined, so pass them statically - List searches now work on MySQL, so applications that patched
mode: 'insensitive'out of the dist files (for example withpatch-package) can drop the patch. SetdatabaseProviderif a startup warning says the database could not be detected - With
controllerAuth, a caller whose token has nocustom:tenantclaim and who names the common tenant inx-tenant-codemay get 403 whencommonTenantCodeis not listed in theCOMMON_TENANT_CODESenvironment variable, because the tenant-override check of the base guard reads that variable. Keep the two in sync - See Migration Guide v1.8.0 for upgrade instructions.
Documentation
- master: Add the framework guide Master data access control and per-system sync, which covers the resolver, the rollout order on the hub and publishing changes to SNS per system (PR #518)
1.7.0 (2026-11-09)
Features
- core: Add the protected
CommandService.getCommandAdmissionConditionshook for atomic command admission. ACommandServicesubclass can return DynamoDBConditionCheckentries, which are committed with the initial command write in a singleTransactWriteItemsrequest. A command is then accepted only if, for example, a maintenance gate is still open at the generation the request observed, which closes the race between a preflight gate check and a gate that closes in the meantime. The default returns no checks and keeps the plainPutItempath, so existing apps behave as before (See Details) (PR #515)- The hook runs for
publishSync,publishAsync, the partial update methods andduplicate, immediately before the initial command is written. An update that changes nothing still returns without calling the hook
- The hook runs for
- core: Add
CommandAdmissionRejectedException(HTTP 409) for a failed admission check andCommandAdmissionContentionException(HTTP 503) for a transaction cancelled byTransactionConflict. A version conflict on the command write is still reported asConditionalCheckFailedException(409), and any other cancellation is rethrown as the originalTransactionCanceledException(500). Core does not retry (See Details) (PR #515) - cli: The infrastructure template now grants
dynamodb:ConditionCheckItemon the stack-prefixed DynamoDB tables, which the admission transaction needs on witness tables (See Details) (PR #515)
Upgrade Notes
- No code changes are needed unless you override the new hook. Unit tests that run a real
CommandServicewith a hand-writtenDynamoDbServicemock that only definesputItemmust also mockputItemWithConditions, becauseCommandServicenow writes every initial command through it (See Details)- With a
createMockauto-mock from@golevelup/ts-jest, the test does not throw, butputItemis never reached becauseputItemWithConditionsis auto-mocked, so assertions onputItemfail without an obvious reason. Assert onputItemWithConditionsinstead, or stub it to callputItem. A spy on theputItemof a realDynamoDbServicekeeps working, becauseputItemWithConditionsdelegates toputItemwhen there are no conditions (PR #516)
- With a
- Using the hook requires
dynamodb:ConditionCheckItemon every witness table. Projects generated from an earlier CLI template must add it by hand - Every item in a transaction consumes double write capacity, even when the transaction is cancelled. Concurrent commands that check the same witness item can cancel each other with
TransactionConflict. This contention has not been measured on the DynamoDB service and DynamoDB Local does not reproduce it, so load test the expected concurrency in a real environment - See Migration Guide v1.7.0 for upgrade instructions.
1.6.0 (2026-11-03)
Breaking Changes
- all packages: Require Node.js 22 or later (
engines.nodeis now>=22). Node.js 18 and 20 are end of life and will not receive the fix for CVE-2026-111497 (Node2Shell), a remote code execution vulnerability in the Brotli decoder bundled with Node.js. The fix ships in Node.js 22.23.4, 24.22.1 and 26.12.1.@mbc-cqrs-serverless/corealso now depends on nodemailer 10, which itself requires Node.js 20 or later. CI tests Node.js 22 and 24 (See Details) (PR #512)- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
npm installreportsEBADENGINE, and fails whenengine-strictis enabled
- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
- core: nodemailer 10 ships its own type definitions, and its default export is no longer a namespace. Code that uses
nodemailer.SendMailOptions,nodemailer.Transporterornodemailer.SentMessageInfomust import these types by name fromnodemailerinstead, and@types/nodemailershould be removed. Apps that only useEmailServiceneed no code changes (See Details) (PR #512) - cli: New projects use Node.js 22. The Lambda function and layer use
NODEJS_22_X, the Docker image is based onnode:22-bookworm-slimand installsopenssl(Prisma's query engine needs libssl, which bookworm-slim does not ship), theinfra-localimages usenode:22-alpine, andserverless.ymlusesnodejs22.xwith serverless-offline^13.9.0. The CDK pipeline pins Node.js 22 for its CodeBuild projects, and@types/nodemoves to 22 (See Details) (PR #512)- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
opensslin the image
- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
Security
- Clear high and critical advisories in production dependencies: proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0, multer 2.5.0, nodemailer 10.3.1, @modelcontextprotocol/sdk 1.32.2, zod 4.6.7 (PR #512)
- The CLI project template's dependency overrides now also pin proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0 and multer 2.5.0, so newly scaffolded projects no longer ship these advisories. The
qsoverride, in the framework and the template, moves to^6.16.1, the minimum that the patched body-parser and express 5 require (PR #512)
Documentation
- mcp-server: Add the v1.5.0 → v1.6.0 migration guide (Node.js 22, nodemailer 10 types) to the
mbc-migrateskill and add Node.js 22 to its compatibility matrix (PR #512)
1.5.0 (2026-09-24)
Breaking Changes
- cli: Replace LocalStack with Floci (
floci/floci:1.6.0) as the local S3 emulator in the scaffolded local development stack. LocalStack Community Edition reached end of life in March 2026. Floci serves S3 on the same port (4566) with path-style addressing, so application code and.envvalues do not change, and deployed environments are not affected (See Details) (PR #503)- Existing projects: replace the
localstackservice ininfra-local/docker-compose.yml, removeserverless-localstack, and add a bucket CORS rule so presigned upload/view URLs keep working in the browser
- Existing projects: replace the
Features
- directory:
DirectoryServicemethods now takeICommandOptionsinstead of an options type that only allowedinvokeContext, so callers can passsourceandrequestIdthrough to the command for tracing. Backward compatible:invokeContextis still the only required field (PR #505)
Bug Fixes
- cli: Fix
mbc newfailing at dependency installation withEOVERRIDE: Override for js-yaml@^4.1.0 conflicts with direct dependency(broken since v1.3.5). The template'sjs-yamloverride now references the direct dependency, which moves to^4.3.2and also clears a high-severityjs-yamladvisory (PR #508) - cli: Fix
npm run migratein newly scaffolded projects. Prisma does not expand the:-default syntax used forLOCAL_RDS_PORTinDATABASE_URL(P1013), andprisma/ddb.tsdid not expand the endpoint variables at all (Invalid URL). Existing projects can apply the same fix: referenceLOCAL_RDS_PORTwithout a:-default inDATABASE_URL, and load.envinprisma/ddb.tswithexpand(dotenv.config())fromdotenv-expand(PR #508) - mcp-server: Ship the Claude Code skills in the published npm package. They were missing from the package, so
mbc install-skillsand the manualcp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/*step could not find them (See Details) (PR #506)
Documentation
- mcp-server: Add the v1.4.0 → v1.5.0 migration guide (LocalStack → Floci, bucket CORS) to the
mbc-migrateskill and update the Floci commands in thembc-debugskill (PR #506)
1.4.0 (2026-08-02)
Features
- core, master, directory, survey-template, ui-setting: Make the DynamoDB table names of the domain modules configurable via a backward-compatible
tableName?option, and addregisterAsyncsupport to all four modules. Defaults are unchanged (master/directory/survey/master), so existing apps upgrade with no code changes (See Details) (PR #493)DirectoryStorageModuleadditionally acceptspkPrefix?(defaultDIRECTORY) andprismaModelName?(defaultdirectory)- The
directory→documentrename (PR #469) is now expressed as opt-in configuration (tableName: 'document',pkPrefix: 'DOCUMENT',prismaModelName: 'document') rather than a forced default
Changes
- master, directory, survey-template:
prismaServiceis now always required at registration (previously validated only whenenableController: true). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. PassprismaServiceexplicitly if you registered withenableController: falseand relied on a globally-provided token - master, ui-setting: When
MasterModuleandSettingModuleshare the defaultmastertable, the framework logs a startup warning if both own themaster_CommandEventHandleralias (data-sync ownership becomes import-order dependent). SetregisterEventHandlerAlias: falseonSettingModulesoMasterModuleowns the alias - master:
MasterModulelogs a warning if itstableNameis overridden — themastertable is a framework-wide config store read at a fixedmaster-dataname byTtlServiceand the sequence package, so renaming it is not fully supported
1.3.5 (2026-08-01)
Bug Fixes
- core: Harden command-handler resume against read-after-write races —
waitConfirmTokennow self-resumes when the predecessor command has already finished, closes the residual TOCTOU window viaSTARTED|FINISHEDstatus checks, retries the predecessorgetItemwith exponential backoff, and classifiescheckNextTokenresume failures so a stuck resume raises an alarm instead of failing silently (PR #465) - core: Add
ConsistentReadsupport toDynamoDbService.getItemand thread it throughCommandService.getItem/getNextCommand, so resume decisions read the latest committed state instead of a possibly stale replica (PR #465) - cli: Fix the scaffolded infra template failing
cdk synth/deploy— the import-CSV Step Functions definition referenced an undefinedaws_stepfunctionsidentifier (corrected tocdk.aws_stepfunctions), which broke every project scaffolded withmbc newon v1.3.4. Upgrade to v1.3.5 to restore deployability (PR #465)
Features
- infra: Add CloudWatch alarms on the command-handler Step Functions state machine (
ExecutionsFailedand degraded self-resume paths), add a 24h timeout and catch onwait_prev_command, and scope theSendTaskSuccessIAM permission to the command state machine ARN (PR #465) - cli: Local development tooling for
mbc newprojects — make the local infra ports configurable viaLOCAL_*_PORTenv vars (defaults unchanged), keep cognito-local's JWT issuer in sync withLOCAL_COGNITO_PORT, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps (PR #337)
Security
- Restore the blocking
npm audit --omit=dev --audit-level=highCI gate that was temporarily disabled, and patchbrace-expansion(top-levelbrace-expansion@2→5.0.8); root production audit: 0 critical/high (PR #482)- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
packages/cli/templates/infra) is not an npm workspace member and ships@aws/pdk(build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in issue #486
- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
1.3.4 (2026-07-17)
Bug Fixes
- core, cli: + `context.--- sidebar_position: 100 sidebar_label: "Backend (Framework)" description: Track all notable changes, new features, and bug fixes in MBC CQRS Serverless releases.
Changelog
All notable changes to MBC CQRS Serverless are documented here. This project follows Semantic Versioning and Conventional Commits.
Version Scheme
x.y.z- Production releasesx.y.z-beta.n- Beta releases for testingx.y.z-alpha.n- Alpha releases for early access
Stable Releases (1.x)
1.8.0 (2026-11-15)
Breaking Changes
- master: Key segments are now validated for every application. A setting code, the
settingCodeandcodeof master data, and theuserIdandgroupIdof group and user settings must be non-empty and must not contain#or@, and a setting code must not beMASTER_SETTING. Otherwise every create, upsert and bulk request,getSetting(GET /api/master-setting/:code) andMasterDataService.list(GET /api/master-data) return 400. Updates and deletes by key (PATCH/DELETE /api/master-setting/:pk/:sk,PUT/DELETE /api/master-data/:pk/:sk) also reject a sort key that contains@. Rows already stored with@in their key are therefore no longer reachable through the API and must be re-created under a valid key (See Details) (PR #518)- In 1.7.0, core cut a sort key at its last
@, the version separator. A value with one@, such as an e-mail address used as auserIdor code, was silently stored under a truncated, different key, and a code with two or more@(for exampleX@Y@Z) could store a row whose key still contains@(MASTER_SETTING#X@Y). Rows whose key contains@can no longer be read, updated or deleted through the API. Find them (a sort key containing@in the DynamoDB data table or the RDS master table) and re-create them under a valid key - A
#in a code built the key of another row, such as a user's personal setting. Master data rows already stored with#in theircodestay readable and can still be updated or deleted by key, but a create or upsert that sends such a code is rejected. Check integrations that generate codes, user IDs or group IDs with#or@before upgrading
- In 1.7.0, core cut a sort key at its last
- master: Setting rows and data rows are now changed only through their own routes.
PUT/DELETE /api/master-data/:pk/:sk(MasterDataService.update/delete) reject aMASTER_SETTING#...key, andPATCH/DELETE /api/master-setting/:pk/:sk(MasterSettingService.updateSetting/deleteSetting) reject a key that is notMASTER_SETTING#followed by a code. Group and user keys such asMASTER_SETTING#USER#u1#S1are still accepted (See Details) (PR #518) - master: Master copy is restricted to system administrators. With
controllerAuthset,POST /api/master-setting/copyrequires thesystem_adminrole from thecustom:rolesclaim; roles incontrollerAuth.writeand group-derived roles do not allow it. With an access resolver registered,MasterSettingService.copyalso requires a write grant whosesystemIdandsettingCodeare both*(See Details) (PR #518) - master:
POST /api/master-bulknow upserts the settings first and the data rows after, instead of both at once, so data rows can use a setting created in the same request. The keys of every item are validated before the first write, but the request is not atomic across settings and data: with an access resolver registered, the access checks of the data items run after the settings are written, so a forbidden data item fails the request and leaves the settings written (See Details) (PR #518) - master:
GET /api/tasks/sfn-task-parentnow resolves the tenant like the rest of the framework: thecustom:tenantclaim wins over thex-tenant-codeheader. It used to read acustom:tenant_codeclaim that nobody sets, so it always took the tenant from the header (PR #518)
Features
- master: Add the opt-in
controllerAuthmodule option, which guards the built-in master routes. Reads need a role inread(default: any logged-in user), writes need a role inwrite(default:system_admin), and the requested tenant must be the caller's tenant unless the request only reads the common tenant or the caller has a cross-tenant role. Without it the routes stay unguarded and the module logs a startup warning (See Details) (PR #518) - master: Scope master data per system. A master setting can carry a
systemId(stored in lower case;sharedis reserved for data every system receives), and its data rows inherit it. Register one class with@MasterAccessResolver()to grant read and write per system and per setting. The services then check the grants in every method, and the list endpoints filter in the SQL query, so pagination and totals stay correct (See Details) (PR #518) - master: Add
GET /api/master-access, which tells a UI whether access control is enabled and returns the caller's grants, andMasterSettingService.assignSystem, which tags existing untagged rows of a setting code with asystemId(See Details) (PR #518) - master: Add
includeCommonto the master setting and master data list searches. It adds the common tenant's rows whose code the caller's tenant does not have (See Details) (PR #518) - master: Add the
commonTenantCodemodule option (the tenant that holds common master data, defaultcommon) and theenableCopyTaskmodule option (registers the master copy handler, default: the value ofenableController) (See Details) (PR #518) - master: Add a nullable
system_idcolumn to the RDS master table of the project template, written by the template's RDS handler, and returnsystemIdat the top level of API responses (See Details) (PR #518) - master, survey-template: Add the
databaseProvidermodule option (postgresqlormysql). By default it is detected from the Prisma client (See Details) (PR #518)
Bug Fixes
- master: Master copy now reads data from the source setting's tenant. It used to read from a hard-coded
meltectenant (PR #518) - master: Master copy now copies sequences. Both keys used to be built from the target tenant, so nothing was ever copied. A target sequence behind the source jumps to the source's value; the write is conditional, so a target that issued numbers in the meantime is never moved back (PR #518)
- master, survey-template: Name, code and keyword searches failed on MySQL, the default database of
mbc new, because they always sent the PostgreSQL-onlymode: 'insensitive'. The setting description search used a JSON path that fit neither database; it now uses['description']on PostgreSQL and'$.description'on MySQL (See Details) (PR #518) - master: A setting update that omits
settingValueno longer clears the setting's attributes, one that omitsnamekeeps the name, and a master data update that omitsseqkeeps it (PR #518)
Upgrade Notes
- For an application that sets neither
controllerAuthnor a resolver, the other changes are: a__systemIdkey sent by a client inattributesis always removed; responses go throughtoPublicRow, so a row stored earlier with a client-planted__systemIdreturns it as a top-levelsystemId;GET /api/master-accessis added when the controllers are enabled; and the DTOs acceptsystemIdandincludeCommon, which are ignored without a resolver - New projects get an empty
controllerAuthobject insrc/master/master.module.ts, so master writes needsystem_adminuntil roles are configured. Existing projects are not changed - With a resolver registered, read methods called without
invokeContextare denied. Server-side code must passinvokeContext, orskipAccessCheck: truefor trusted internal work - Applications generated earlier must add a nullable
system_idcolumn and writesystemId: getSystemId(cmd)in their own RDS handler before registering a resolver, becauseupdate-scheme.tsdoes not change an existing schema or handler. With a resolver registered, the application refuses to start if the PrismaMastermodel has nosystemIdfield - With a resolver registered, creating a tenant-level override of a common setting that has no
systemIdtreats that setting asshared: a requestedsystemIdother thansharedis rejected with 400, write access tosharedis required, and the override stores nosystemId includeCommonis bounded. A master data list withincludeCommonrequiressettingCodeunless the caller is in the common tenant, and a tenant holding more than 10,000 matching rows gets a 400 instead of a database error; results are not truncated. A settings list withincludeCommondoes not merge the common tenant's group and user setting rows- With
registerAsync, the staticcommonTenantCode,databaseProviderandcontrollerAuthoptions override the values the factory returns, even when the static value is undefined, so pass them statically - List searches now work on MySQL, so applications that patched
mode: 'insensitive'out of the dist files (for example withpatch-package) can drop the patch. SetdatabaseProviderif a startup warning says the database could not be detected - With
controllerAuth, a caller whose token has nocustom:tenantclaim and who names the common tenant inx-tenant-codemay get 403 whencommonTenantCodeis not listed in theCOMMON_TENANT_CODESenvironment variable, because the tenant-override check of the base guard reads that variable. Keep the two in sync - See Migration Guide v1.8.0 for upgrade instructions.
Documentation
- master: Add the framework guide Master data access control and per-system sync, which covers the resolver, the rollout order on the hub and publishing changes to SNS per system (PR #518)
1.7.0 (2026-11-09)
Features
- core: Add the protected
CommandService.getCommandAdmissionConditionshook for atomic command admission. ACommandServicesubclass can return DynamoDBConditionCheckentries, which are committed with the initial command write in a singleTransactWriteItemsrequest. A command is then accepted only if, for example, a maintenance gate is still open at the generation the request observed, which closes the race between a preflight gate check and a gate that closes in the meantime. The default returns no checks and keeps the plainPutItempath, so existing apps behave as before (See Details) (PR #515)- The hook runs for
publishSync,publishAsync, the partial update methods andduplicate, immediately before the initial command is written. An update that changes nothing still returns without calling the hook
- The hook runs for
- core: Add
CommandAdmissionRejectedException(HTTP 409) for a failed admission check andCommandAdmissionContentionException(HTTP 503) for a transaction cancelled byTransactionConflict. A version conflict on the command write is still reported asConditionalCheckFailedException(409), and any other cancellation is rethrown as the originalTransactionCanceledException(500). Core does not retry (See Details) (PR #515) - cli: The infrastructure template now grants
dynamodb:ConditionCheckItemon the stack-prefixed DynamoDB tables, which the admission transaction needs on witness tables (See Details) (PR #515)
Upgrade Notes
- No code changes are needed unless you override the new hook. Unit tests that run a real
CommandServicewith a hand-writtenDynamoDbServicemock that only definesputItemmust also mockputItemWithConditions, becauseCommandServicenow writes every initial command through it (See Details)- With a
createMockauto-mock from@golevelup/ts-jest, the test does not throw, butputItemis never reached becauseputItemWithConditionsis auto-mocked, so assertions onputItemfail without an obvious reason. Assert onputItemWithConditionsinstead, or stub it to callputItem. A spy on theputItemof a realDynamoDbServicekeeps working, becauseputItemWithConditionsdelegates toputItemwhen there are no conditions (PR #516)
- With a
- Using the hook requires
dynamodb:ConditionCheckItemon every witness table. Projects generated from an earlier CLI template must add it by hand - Every item in a transaction consumes double write capacity, even when the transaction is cancelled. Concurrent commands that check the same witness item can cancel each other with
TransactionConflict. This contention has not been measured on the DynamoDB service and DynamoDB Local does not reproduce it, so load test the expected concurrency in a real environment - See Migration Guide v1.7.0 for upgrade instructions.
1.6.0 (2026-11-03)
Breaking Changes
- all packages: Require Node.js 22 or later (
engines.nodeis now>=22). Node.js 18 and 20 are end of life and will not receive the fix for CVE-2026-111497 (Node2Shell), a remote code execution vulnerability in the Brotli decoder bundled with Node.js. The fix ships in Node.js 22.23.4, 24.22.1 and 26.12.1.@mbc-cqrs-serverless/corealso now depends on nodemailer 10, which itself requires Node.js 20 or later. CI tests Node.js 22 and 24 (See Details) (PR #512)- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
npm installreportsEBADENGINE, and fails whenengine-strictis enabled
- Migration: run your application, Lambda functions and Docker images on Node.js 22.23.4 or later. On Node.js 18 or 20,
- core: nodemailer 10 ships its own type definitions, and its default export is no longer a namespace. Code that uses
nodemailer.SendMailOptions,nodemailer.Transporterornodemailer.SentMessageInfomust import these types by name fromnodemailerinstead, and@types/nodemailershould be removed. Apps that only useEmailServiceneed no code changes (See Details) (PR #512) - cli: New projects use Node.js 22. The Lambda function and layer use
NODEJS_22_X, the Docker image is based onnode:22-bookworm-slimand installsopenssl(Prisma's query engine needs libssl, which bookworm-slim does not ship), theinfra-localimages usenode:22-alpine, andserverless.ymlusesnodejs22.xwith serverless-offline^13.9.0. The CDK pipeline pins Node.js 22 for its CodeBuild projects, and@types/nodemoves to 22 (See Details) (PR #512)- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
opensslin the image
- Existing projects are not changed. To follow, update the same places by hand. If you move a Dockerfile to bookworm-slim and use Prisma, also install
Security
- Clear high and critical advisories in production dependencies: proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0, multer 2.5.0, nodemailer 10.3.1, @modelcontextprotocol/sdk 1.32.2, zod 4.6.7 (PR #512)
- The CLI project template's dependency overrides now also pin proxy-addr 2.0.8, body-parser 1.20.9 / 2.4.0 and multer 2.5.0, so newly scaffolded projects no longer ship these advisories. The
qsoverride, in the framework and the template, moves to^6.16.1, the minimum that the patched body-parser and express 5 require (PR #512)
Documentation
- mcp-server: Add the v1.5.0 → v1.6.0 migration guide (Node.js 22, nodemailer 10 types) to the
mbc-migrateskill and add Node.js 22 to its compatibility matrix (PR #512)
1.5.0 (2026-09-24)
Breaking Changes
- cli: Replace LocalStack with Floci (
floci/floci:1.6.0) as the local S3 emulator in the scaffolded local development stack. LocalStack Community Edition reached end of life in March 2026. Floci serves S3 on the same port (4566) with path-style addressing, so application code and.envvalues do not change, and deployed environments are not affected (See Details) (PR #503)- Existing projects: replace the
localstackservice ininfra-local/docker-compose.yml, removeserverless-localstack, and add a bucket CORS rule so presigned upload/view URLs keep working in the browser
- Existing projects: replace the
Features
- directory:
DirectoryServicemethods now takeICommandOptionsinstead of an options type that only allowedinvokeContext, so callers can passsourceandrequestIdthrough to the command for tracing. Backward compatible:invokeContextis still the only required field (PR #505)
Bug Fixes
- cli: Fix
mbc newfailing at dependency installation withEOVERRIDE: Override for js-yaml@^4.1.0 conflicts with direct dependency(broken since v1.3.5). The template'sjs-yamloverride now references the direct dependency, which moves to^4.3.2and also clears a high-severityjs-yamladvisory (PR #508) - cli: Fix
npm run migratein newly scaffolded projects. Prisma does not expand the:-default syntax used forLOCAL_RDS_PORTinDATABASE_URL(P1013), andprisma/ddb.tsdid not expand the endpoint variables at all (Invalid URL). Existing projects can apply the same fix: referenceLOCAL_RDS_PORTwithout a:-default inDATABASE_URL, and load.envinprisma/ddb.tswithexpand(dotenv.config())fromdotenv-expand(PR #508) - mcp-server: Ship the Claude Code skills in the published npm package. They were missing from the package, so
mbc install-skillsand the manualcp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/*step could not find them (See Details) (PR #506)
Documentation
- mcp-server: Add the v1.4.0 → v1.5.0 migration guide (LocalStack → Floci, bucket CORS) to the
mbc-migrateskill and update the Floci commands in thembc-debugskill (PR #506)
1.4.0 (2026-08-02)
Features
- core, master, directory, survey-template, ui-setting: Make the DynamoDB table names of the domain modules configurable via a backward-compatible
tableName?option, and addregisterAsyncsupport to all four modules. Defaults are unchanged (master/directory/survey/master), so existing apps upgrade with no code changes (See Details) (PR #493)DirectoryStorageModuleadditionally acceptspkPrefix?(defaultDIRECTORY) andprismaModelName?(defaultdirectory)- The
directory→documentrename (PR #469) is now expressed as opt-in configuration (tableName: 'document',pkPrefix: 'DOCUMENT',prismaModelName: 'document') rather than a forced default
Changes
- master, directory, survey-template:
prismaServiceis now always required at registration (previously validated only whenenableController: true). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. PassprismaServiceexplicitly if you registered withenableController: falseand relied on a globally-provided token - master, ui-setting: When
MasterModuleandSettingModuleshare the defaultmastertable, the framework logs a startup warning if both own themaster_CommandEventHandleralias (data-sync ownership becomes import-order dependent). SetregisterEventHandlerAlias: falseonSettingModulesoMasterModuleowns the alias - master:
MasterModulelogs a warning if itstableNameis overridden — themastertable is a framework-wide config store read at a fixedmaster-dataname byTtlServiceand the sequence package, so renaming it is not fully supported
1.3.5 (2026-08-01)
Bug Fixes
- core: Harden command-handler resume against read-after-write races —
waitConfirmTokennow self-resumes when the predecessor command has already finished, closes the residual TOCTOU window viaSTARTED|FINISHEDstatus checks, retries the predecessorgetItemwith exponential backoff, and classifiescheckNextTokenresume failures so a stuck resume raises an alarm instead of failing silently (PR #465) - core: Add
ConsistentReadsupport toDynamoDbService.getItemand thread it throughCommandService.getItem/getNextCommand, so resume decisions read the latest committed state instead of a possibly stale replica (PR #465) - cli: Fix the scaffolded infra template failing
cdk synth/deploy— the import-CSV Step Functions definition referenced an undefinedaws_stepfunctionsidentifier (corrected tocdk.aws_stepfunctions), which broke every project scaffolded withmbc newon v1.3.4. Upgrade to v1.3.5 to restore deployability (PR #465)
Features
- infra: Add CloudWatch alarms on the command-handler Step Functions state machine (
ExecutionsFailedand degraded self-resume paths), add a 24h timeout and catch onwait_prev_command, and scope theSendTaskSuccessIAM permission to the command state machine ARN (PR #465) - cli: Local development tooling for
mbc newprojects — make the local infra ports configurable viaLOCAL_*_PORTenv vars (defaults unchanged), keep cognito-local's JWT issuer in sync withLOCAL_COGNITO_PORT, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps (PR #337)
Security
- Restore the blocking
npm audit --omit=dev --audit-level=highCI gate that was temporarily disabled, and patchbrace-expansion(top-levelbrace-expansion@2→5.0.8); root production audit: 0 critical/high (PR #482)- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
packages/cli/templates/infra) is not an npm workspace member and ships@aws/pdk(build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in issue #486
- Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (
1.3.4 (2026-07-17)
Bug Fixes
- core, cli: ), so inline attributes above ~110 KB could trigger
States.DataLimitExceeded(See Details) (PR #466) - mcp-server: Update skills with guidance on the new
ATTRIBUTE_LIMIT_SIZEdefault (PR #470)
1.3.2 (2026-06-27)
Features
- mcp-server: Add AP028, AP029, AP030 anti-pattern detectors (See Details) (PR #460, PR #461)
- AP028: Duplicate
DataSyncHandlerregistration across NestJS modules — detected and deduplicated with a warning log - AP029: Reserved
'dynamodb'type on@DataSyncHandlercauses the handler to be silently excluded from dispatch - AP030: Fully-qualified table name (ending in
'-command') in@DataSyncHandlercauses silent handler skip
- AP028: Duplicate
Bug Fixes
- core: Fix
DataSyncHandlerduplicate registration —ExplorerServicenow deduplicates handlers viaSet;CommandServicededuplicates viaMap<constructor.name, instance>and emits awarnlog for each removed duplicate (PR #459) - core: Fix
publishSync— versionedskis now assigned tocommand.skbefore handler dispatch soIDataSyncHandler.up()receives the correct key;updateStatuserrors are no longer silently masked;pk/skare now included incheckNextTokenwarn logs (See Details) (PR #460)
Security
- Harden npm dependencies — resolve high/moderate vulnerabilities via
overrides(lodash,tmp,multer,ajv,picomatch,fast-xml-parser) and targeted upgrades (@nestjs/config^4.0.4,@typescript-eslintv8); root production audit: 0 critical/high (PR #445–#453) - cli: Upgrade
multerto v2.2.0 in scaffolded templates to fix CVE-2026-5079 (DoS via deeply nested multipart field names) (PR #463) - Add blocking CI gates:
npm audit --omit=dev --audit-level=highand ESLint startup check run on every PR, failing the build on any production vulnerability (PR #448)
1.3.1 (2026-06-02)
Features
- core: Add group-based role authorization —
RolesGuardchecks direct roles fromcustom:rolesfirst, then roles derived from the user's groups in the newcustom:groupsclaim (See Details) (PR #440)- New
@GroupRoleResolver()decorator andIGroupRoleResolverinterface — implement exactly one resolver per app to map group IDs to roles (loaded from DynamoDB/RDS/config); the mapping is not stored in the JWT UserContextgainstenantRoles(direct roles array) andtenantGroupIds(group IDs for the active tenant);tenantRole(singular) is kept for backward compatibility- Opt-in: existing
@Roles()checks keep working with no code changes - A resolver failure propagates as a 5xx (not a silent 403), so a backend outage is distinguishable from a genuine access denial
- New
- mcp-server: Update skills and analyzer for v1.3.1
- AP027 anti-pattern detector added: a
@GroupRoleResolver()class must not also be annotated with@Injectable() mbc-migrateskill: v1.3.1 migration guide addedmbc-generateskill: group role resolver code generation template addedmbc-reviewskill: AP022 (group role resolver) added to checklist
- AP027 anti-pattern detector added: a
Bug Fixes
- core: Tolerate a malformed
custom:groupsclaim (fail-closed to no group roles) instead of throwing, so a bad token degrades to direct-role-only checks rather than crashing the request - See Migration Guide v1.3.1 for upgrade instructions.
1.3.0 (2026-05-21)
Features
- core: Add
AppSyncEventsService— opt-in HTTP pub/sub transport for real-time notifications via AWS AppSync Events API (See Details) (PR #433)- Transport selection via
NOTIFICATION_TRANSPORTSenv var (comma-separated); defaultappsync-graphql— existing GraphQL Subscription behavior is unchanged - Channel structure:
/{namespace}/{tenantCode}/{action}/{sanitizedId}— clients subscribe at any granularity using AppSync wildcard (/*) - Authentication: IAM SigV4 for Lambda/ECS publish; API key for client subscriptions
- Dual-publish mode:
NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-eventto publish to both transports simultaneously during migration - New environment variables:
NOTIFICATION_TRANSPORTS,APPSYNC_EVENTS_ENDPOINT,APPSYNC_EVENTS_NAMESPACE(See Details) @NotificationTransportdecorator: pluggable transport registration — custom transports can be added without modifying framework code
- Transport selection via
- cli: CDK infra template: add
appsyncEventsandnotificationTransportstoConfigtype — provisionsEventApi+ChannelNamespace, injectsNOTIFICATION_TRANSPORTS,APPSYNC_EVENTS_ENDPOINT, andAPPSYNC_EVENTS_NAMESPACEinto Lambda and ECS, and grantsappsync:EventPublishIAM permission viagrantPublish()automatically - mcp-server: Update skills and analyzer for v1.3.0 (PR #436)
- AP026 anti-pattern detector added:
@NotificationTransportimplementors must not also be annotated with@Injectable mbc-migrateskill: v1.3.0 migration guide and version compatibility table updatedmbc-generateskill: custom notification transport code generation template addedmbc-reviewskill: AP026 added to checklist
- AP026 anti-pattern detector added:
- See Migration Guide v1.3.0 for upgrade instructions.
1.2.6 (2026-05-06)
Features
- core: Repository Read-Your-Writes (RYW) improvements — proactively purge stale RYW sessions when the data table catches up to or surpasses the session version, eliminating "stale override" reads (See Details) (PR #410)
getItem: whenexisting.version >= session.version, the session is purged in the background and persisted data is returned directly (skipping the unnecessary command-table read)listItemsByPk: synchronized sessions are cleaned up in-place during the merge looplistItems(RDS path): per-session checks are now parallelized viaPromise.all, eliminating sequential N+1 latency- New optional
mergeOptions.getVersionlets callers skip the extra DynamoDB GetItem when the existing RDS row already proves caught-up SessionService.delete()andDynamoDbService.deleteItem()added; both safe for fire-and-forget use- Backward-compatible:
getVersionis optional; projects withRYW_SESSION_TTL_MINUTESunset are unaffected
- mcp-server: Add AP021 anti-pattern detector —
Event Emit Directly After publishAsync in CommandService(Severity: High) (See Details) (PR #408)- Detects
eventEmitter.emit()calls within 200 chars aftercommandService.publishAsync/publishSync - Recommendation: emit events from
IDataSyncHandler.up()/down()instead, since the data table is populated asynchronously via DynamoDB Streams afterpublishAsync
- Detects
- mcp-server: Add cross-reference table mapping detector AP codes (
analyze.ts) to skill-doc AP codes (skills/mbc-review/SKILL.md) — the two systems use independent numbering and only AP016–AP019 and AP021 share codes (PR #411)- Detector output now annotates each hit with its corresponding skill-doc AP code, e.g.
AP005: Hardcoded Tenant (skill-doc: AP002) mbc-migrateskill: added v1.2.5 and v1.2.6 sections with migration matrix entriesmbc-debugskill: added troubleshooting entry for the (intentional) early RYW session purge in v1.2.6
- Detector output now annotates each hit with its corresponding skill-doc AP code, e.g.
Bug Fixes
- mcp-server:
server.tswas hardcoding the package version, which silently drifted on everylerna versionbump. Now read at runtime frompackage.json(PR #411)
1.2.5 (2026-04-10)
Features
- import: Refactor ZIP import processing — move ZIP job handling directly into
ImportService, removing the separateZipImportQueueEventHandler(See Details) (PR #404)ZipImportQueueEventHandlerhas been removed; ZIP import jobs are now processed directly withinImportServiceImportEventHandlernow skips SQS publishing forZIP_MASTER_JOBevents- Enhanced ZIP import validation in
CreateZipImportDto - Improved error handling and logging for ZIP processing
- mcp-server: Add AP016–AP020 anti-pattern detectors to
mbc_check_anti_patternstool (total: 20 patterns) (PR #403)- AP016: Missing Error Logging Before Rethrow (High)
- AP017: Incorrect Attribute Merging on Partial Update (High)
- AP018: Missing Swagger Documentation /
@ApiTags(Low) - AP019: Missing Pagination in List Queries (High)
- AP020: Missing
getCommandSourcefor Tracing (Low)
- mcp-server: Update
mbc-migrateandmbc-debugskills with v1.1.x and v1.2.x breaking change guidance (PR #403)
Dependencies
- mcp-server: Update
@modelcontextprotocol/sdkfrom 1.26.0 to 1.29.0 (PR #403)
1.2.4 (2026-04-09)
Features
- task:
TaskModule.register()now returns a global module, eliminating the need to register it in multiple feature modules (PR #398)- Previously,
TaskModule.register()had to be called in each module that needed task functionality; now register it once inAppModule
- Previously,
- mcp-server: Add AP015 anti-pattern detector — detects duplicate
TaskModule.register()calls (now redundant in v1.2.4+) (PR #399)
1.2.3 (2026-04-08)
Bug Fixes
- import: Fix Head-of-Line Blocking (Poison Pill) in
CsvBatchProcessorby implementing Smart Retry pattern (See Details) (PR #394)- Previously, a persistent validation error on the first row caused the entire batch to crash immediately
- Now, each row is processed independently; errors are collected and a single aggregated error is thrown after the full batch is processed
- Valid rows are saved successfully; failed rows trigger SQS retry; already-succeeded rows are skipped on retry via EQUAL comparison (idempotency maintained)
- import: Fix
ImportQueueEventHandlerpassing raw SQS payload instead of parsedimportEventtoSingleImportProcessor(PR #394)singleImportProcessor.process()now receivesevent.importEvent(parsed, rich object) instead ofevent.payload(raw SQS payload)
1.2.2 (2026-04-08)
Features
- import: Enhance import processing with SQS integration and parent job counter tracking (PR #387)
ImportQueueEventHandlernow publishes sub-job events to SQS for distributed processing- Parent job counter increments correctly when child jobs are enqueued
- import: Fix
CsvImportSfnEventHandlerto process both SUCCEEDED and FAILED Step Functions results (PR #387)
Bug Fixes
- core: Handle malformed JWT tokens gracefully in
extractInvokeContext(PR #388)- Prevents authentication failures caused by corrupted or unexpected JWT payloads
1.2.1 (2026-04-06)
Features
- core: Add
SqsServiceandSqsClientFactoryfor SQS message operations (See Details) (PR #383)sendMessage()— send a single message to an SQS queuesendMessageBatch()— send up to 10 messages in a single API callreceiveMessages()— receive messages with configurableMaxNumberOfMessages(default: 10) andWaitTimeSeconds(default: 0)deleteMessage()— acknowledge and delete a single processed messagedeleteMessageBatch()— delete up to 10 messages in a single API callSqsServiceis registered inQueueModule(global) and injectable across the application- Supports
MessageSystemAttributeNamesfor receiving system attributes (deprecatedAttributeNamesnot exposed)
- core: Refactor
SnsClientFactoryto use a singletonSNSClientinstance (PR #383)- Previously cached a separate client per topic ARN; now a single instance is shared across all publish calls
getClient()signature changed fromgetClient(topicArn: string)togetClient()
1.2.0 (2026-04-02)
Breaking Changes
- core:
publishSync()andpublishPartialUpdateSync()now returnnullwhen the command is not dirty (no-op) (See Details) (PR #375)- Return type changes from
Promise<CommandModel>toPromise<CommandModel | null> - Matches the existing behavior of
publishAsync()andpublishPartialUpdateAsync() - Migration: add a null check before accessing any property on the result
- Return type changes from
Features
- core: Add Read-Your-Writes (RYW) consistency via
SessionServiceandRepository(See Details) (PR #375)- After
publishAsync, subsequent reads by the same user now return pending command data before the DynamoDB Stream sync completes - Opt-in: set
RYW_SESSION_TTL_MINUTESenvironment variable to enable (e.g.5) - New
Repositoryclass exported fromCommandModule/@mbc-cqrs-serverless/core— wrapsDataServicewith RYW merge forgetItem,listItemsByPk,listItems - Session table
{NODE_ENV}-{APP_NAME}-sessionmust be created (seedynamodbs/session.json) - No effect when
RYW_SESSION_TTL_MINUTESis unset — zero impact on existing projects
- After
- mcp-server: Add AP013 and AP014 anti-pattern detectors for v1.2.0 breaking changes (PR #377)
- AP013: detects
publishSync/publishPartialUpdateSyncresult used without null check - AP014: detects deprecated
genNewSequence()usage migration_guideprompt updated with v1.2.0 sections
- AP013: detects
- See Migration Guide v1.2.0 for detailed upgrade instructions for both breaking changes.
Bug Fixes
- import: Fix import status handling for ZIP orchestrator (PR #370)
ImportStatusHandlernow sends task success withimportJobStatuswhen the job failsZipImportSfnEventHandleraggregates CSV task failure counts and adjusts final job status
1.1.6 (2026-03-30)
Bug Fixes
- import: Fix import status handling for ZIP orchestrator (PR #371) (backport from v1.2.0)
ImportStatusHandlernow sends task success withimportJobStatuswhen the job failsZipImportSfnEventHandleraggregates CSV task failure counts and adjusts final job status
1.1.5 (2026-03-28)
Features
- import: Implement v2 batch processing architecture for high-throughput CSV imports (See Details) (PR #366)
- Replace per-row
import_tmpwrites with direct in-Lambda command publishing, eliminating Hot Partition bottlenecks - Distributed Map now configured with
MaxItemsPerBatch: 100andMaxConcurrency: 50for significantly higher throughput - New
finalize_parent_jobstate aggregates batch summaries and writes final job status in a single DynamoDBUpdateItemcall - Remove per-row atomic counter updates from
CommandFinishedHandler, eliminating DynamoDB throttling at scale - Add
ImportPublishModeenum (SYNC/ASYNC) toImportEntityProfilefor per-entity publish mode configuration - Add empty
processingResultsguard: job is markedFAILEDif no batch results are received
- Replace per-row
Breaking Changes
- import: CSV import no longer provides real-time row-level progress tracking (See Details)
processedRows,succeededRows,failedRowscounters are now aggregated once when Step Functions execution completes- Individual CSV rows are no longer written to the
import_tmpDynamoDB table - The
import-csvstate machine requires a newfinalize_parent_jobstate andresultPath: '$.processingResults'— CDK andserverless.ymlmust be updated together with this package
Tests
- Add SYNC/ASYNC routing tests for
ImportQueueEventHandler(6 test cases covering EQUAL/NOT_EXIST/CHANGED × SYNC/ASYNC + fallback) - Add empty
processingResultsguard test forCsvImportSfnEventHandler - Add batch aggregation tests (1,000 + 500 rows, COMPLETED and FAILED scenarios)
1.1.4 (2026-03-27)
Features
- core: Restore audit trail and history parity for
publishSync(See Details) (PR #363)publishSyncnow writes an immutable event to the Command table withstatus: 'publish_sync:STARTED'andsyncMode: 'SYNC'- History table is now populated by
publishSync, matching the async Step Functions pipeline - Command lifecycle follows
publish_sync:STARTED→finish:FINISHED(orpublish_sync:FAILEDon error) - Ported
isNotCommandDirtyearly-return optimization frompublishAsync— returnsnullwhen no changes detected - DynamoDB Stream filter updated to exclude
syncMode=SYNCrecords, preventing Step Functions double-execution DefaultEventFactoryalso filterssyncMode=SYNCrecords for local development environments
Tests
- Add comprehensive tests for
publishSyncaudit trail and history parity
1.1.3 (2026-03-24)
Bug Fixes
- import: Fix CSV import Distributed Map state result exceeding 256KB limit (See Details) (PR #348)
- Set
resultPath: DISCARDon Distributed Map to prevent child execution results from being aggregated into state data - Remove
MapResultdependency fromCsvImportSfnEventHandler, usecountCsvRows()from S3 instead - Add error handling for cases where the S3 stream is not readable
- Set
CI/CD
- Switch to npm OIDC trusted publishing, removing dependency on
NPM_TOKENsecret (PR #357)- Upgrade lerna from v8 to v9 for built-in OIDC support
- Add
id-token: writepermission to publish job - Add lockfile sync step for Node 22+ compatibility
Tests
- Add comprehensive tests for
CsvImportSfnEventHandlerfinalize_parent_job logic- Test FAILED status when failedRows > 0
- Test COMPLETED status when all rows succeed
- Test no status update when processing is incomplete
- Test error handling when S3 stream is not readable
1.1.2 (2026-02-25)
Features
- master: Add built-in upsert methods for master settings and data (See Details)
upsertTenantSetting(),upsertSetting(),upsertBulk()for MasterSettingServiceupsert(),upsertSetting(),upsertBulk()for MasterDataService- Automatically creates new records, updates changed records, and skips unchanged records
- Supports recreating soft-deleted records
- master: Add unified bulk upsert API (
/api/master-bulk/) (See Details)- Single endpoint that handles both settings and data items
- Items routed by presence of
settingCodefield - Preserves original input order in response
- Tenant code validation enforced
- master: Add
@ArrayMaxSize(100)validation to all bulk DTOs - master: Add tenant code validation to individual bulk endpoints (
/api/master-setting/bulk,/api/master-data/bulk)
Bug Fixes
- core: Fix
checkVersionerror message using hardcoded value instead of actualcommandVersion(PR #331) - master: Fix
seq === 0being treated as falsy increateSettingby changing to null check (seq == null) - master: Fix DTO mutation in
createSettingby cloning attributes before modifying seq
Tests
- Add comprehensive unit tests for MasterBulkController (8 test cases)
- Add unit tests for MasterDataService upsert and upsertBulk methods
- Add unit tests for MasterSettingService upsertTenantSetting and upsertBulk methods
- Add integration tests for master data and setting upsert scenarios
1.1.1 (2026-02-07)
Bug Fixes
- cli: Add missing
import_tmp.jsonDynamoDB table template (See Details) (PR #323)- The
import_tmptable definition was missing from CLI templates, causingnpm run offline:slsto fail - The
serverless.ymlreferencesLOCAL_DDB_IMPORT_TMP_STREAMenvironment variable, which requires the table to be created during migration - See Common Issues for workaround if using older versions
- The
1.1.0 (2026-02-03)
Breaking Changes
- tenant: Change
TENANT_COMMONenum value from'COMMON'to'common'(lowercase)- This change affects partition key format:
TENANT#COMMON→TENANT#common - Migration required: Existing data with
TENANT#COMMONpartition keys needs to be migrated - See Migration Guide for detailed instructions
- This change affects partition key format:
- core: Remove deprecated
CommandService.publish()method (See Details)- Use
CommandService.publishAsync()instead
- Use
- core: Remove deprecated
CommandService.publishPartialUpdate()method- Use
CommandService.publishPartialUpdateAsync()instead
- Use
- sequence: Remove deprecated
SequencesService.genNewSequence()method- Use
SequencesService.generateSequenceItem()instead
- Use
Features
- core: Add tenant code normalization for case-insensitive matching (See Details)
- Tenant codes are now automatically normalized to lowercase
getUserContext()returns normalized tenant code- All DynamoDB operations use normalized tenant codes for consistency
- core: Add
normalizeTenantCode()utility function for explicit normalization - core: Add
isCommonTenant()utility function for common tenant detection - core: Add EmailTags support for AWS SES email categorization and filtering (See Details)
- New
emailTagsoption inEmailNotificationinterface - Tags are passed to SES for email categorization and tracking
- New
- core: Add extensible tenant verification in RolesGuard (See Details)
isHeaderOverride(): Detect header-based tenant overridecanOverrideTenant(): Check permission for cross-tenant accessgetCommonTenantCodes(): Configurable common tenant listgetCrossTenantRoles(): Configurable cross-tenant roles (default: 'system_admin')
- cli: Add npm registry version check for skill updates
- Fetch latest version from npm registry instead of local package.json
- 24-hour cache to reduce network requests
- Offline fallback to cached version
Security
- core: Restrict tenant code header override to system admin only
- Previously, users without
custom:tenantCognito attribute could specify any tenant via header - Now only users with global
system_adminrole can override tenant code viax-tenant-codeheader - Regular users must have
custom:tenantset in Cognito
- Previously, users without
Bug Fixes
- master: Fix
TENANT_COMMONconstant usage in MasterSettingService and MasterDataService- Previously hardcoded
'COMMON'strings are now usingSettingTypeEnum.TENANT_COMMON - Ensures consistent partition key generation across the framework
- Previously hardcoded
Tests
- tenant: Add comprehensive tests for TenantService methods
getTenant(): Retrieval testsupdateTenant(): Update and attribute merge testsdeleteTenant(): Soft delete testsaddTenantGroup(): Group management testscustomizeSettingGroups(): Setting customization testscreateTenantGroup(): Tenant group creation tests
- tenant: Add SettingTypeEnum validation tests
- Verify
TENANT_COMMON = 'common'(lowercase) - Ensure enum completeness and consistency
- Verify
- core: Add tenant code normalization tests (70+ test cases)
- core: Add tenant normalization command tests (30+ test cases)
- core: Add comprehensive dependency integration tests (3400+ tests)
- AWS SDK integration tests (DynamoDB, S3, SNS, SQS, Step Functions, SES)
- NestJS behavior tests (decorators, config, DI, Swagger)
- Third-party library tests (class-transformer, class-validator, RxJS)
Documentation
- Add migration guide for v1.1.0 tenant code changes
1.0.26 (2026-01-26)
Features
- cli: Add configurable local service ports via environment variables (See Details) (PR #300)
- Support for
LOCAL_HTTP_PORT,LOCAL_DYNAMODB_PORT,LOCAL_RDS_PORT, and other port variables - Allows users to resolve port conflicts with other services
- Configuration is automatically applied to Docker Compose, Serverless Offline, and trigger scripts
- Support for
Security
- Update
diffpackage from 4.0.2 to 4.0.4 for security fix (PR #297, PR #299) - Update
lodashpackage from 4.17.21 to 4.17.23 for prototype pollution fix (PR #298)
1.0.25 (2026-01-19)
Features
- core: Enhanced inline template email with advanced variable substitution (See Details)
- Support for nested property access in template variables (e.g., user.profile.name in double-brace placeholders)
- Support for Unicode/Japanese keys in template variables
- Whitespace trimming inside placeholders so spaces around the variable name are ignored
- Improved local development fallback for template compilation
1.0.24 (2026-01-17)
Features
- mcp-server: Add Claude Code Skills for guided development assistance (See Details)
/mbc-generate: Generate boilerplate code (modules, services, controllers, DTOs, handlers)/mbc-review: Review code for best practices and anti-patterns (20 patterns)/mbc-migrate: Guide version migrations and breaking changes/mbc-debug: Debug and troubleshoot common issues- Skills are distributed via npm package and can be installed to
~/.claude/skills/or.claude/skills/
- cli: Add
mbc install-skillscommand for easy skills installation (See Details)- Install skills to personal directory (
~/.claude/skills/) or project directory (.claude/skills/) - Options:
--project,--force,--list
- Install skills to personal directory (
Bug Fixes
- core: Fix typo in parameter name
skExpessiontoskExpression- Affected packages: core, directory, master, task, ui-setting
- This was a breaking change for TypeScript users who referenced the old parameter name
1.0.23 (2026-01-16)
Features
- core: Add inline template email support with
sendInlineTemplateEmail()method (See Details)- New
sendInlineTemplateEmail(msg: TemplatedEmailNotification)method in EmailService - Support for inline HTML/text templates with dynamic data substitution
- Local development fallback with manual template compilation when SES is unavailable
- New interfaces:
InlineTemplateContent,TemplatedEmailNotification
- New
1.0.22 (2026-01-16)
Features
- mcp-server: Add code analysis tools for AI-assisted development (See Details)
mbc_check_anti_patterns: Detect common anti-patterns in code with severity levelsmbc_health_check: Project health check (dependencies, structure, configuration)mbc_explain_code: Analyze and explain code in MBC CQRS context
Bug Fixes
- mcp-server: Improve code analysis tools robustness
- Renumber anti-patterns sequentially (AP001-AP010)
- Limit regex match range to prevent false positives
- Add error handling for file reading and JSON parsing
- Add 18 unit tests for analyze tools
Security
- Fix security vulnerabilities in dependencies: qs, express, body-parser
Dependencies
- Bump qs from 6.13.0 to 6.14.1
- Bump @nestjs/platform-express from 10.4.20 to 10.4.22
- Bump express from 4.21.2 to 4.22.1
- Bump body-parser from 1.20.3 to 1.20.4
1.0.21 (2026-01-15)
Features
- import: Add ZIP finalization hooks support to ImportModule
- New
IZipFinalizationHookinterface for custom post-import processing - Register hooks via
zipFinalizationHooksoption inImportModule.register() - Hooks receive
ZipFinalizationContextwith results, status, and execution input
- New
1.0.20 (2026-01-11)
Bug Fixes
- import: Fix Step Functions CSV handler always setting COMPLETED status regardless of child job failures
- Fixed
CsvImportSfnEventHandler.finalizeParentJob()to correctly set status to FAILED when any child job fails - Fixed
CsvImportSfnEventHandlerincsv_loaderstate to correctly set status when early finalization occurs with failures - Previously, the ternary operator was incorrectly returning COMPLETED for both cases:
failedRows > 0 ? COMPLETED : COMPLETED - Now correctly returns FAILED when failedRows > 0:
failedRows > 0 ? FAILED : COMPLETED - This bug caused Step Functions to report SUCCESS even when child import jobs failed
- See CsvImportSfnEventHandler for details
- Fixed
1.0.19 (2026-01-11)
Bug Fixes
- import: Fix master job status not updating to FAILED when child import jobs fail
- Previously, when a child import job failed with errors like
ConditionalCheckFailedException, the master job status remainedPROCESSINGindefinitely - Fixed
incrementParentJobCountersto correctly set master job status toFAILEDwhen any child job fails (was always setting toCOMPLETED) - Fixed
ImportQueueEventHandler.handleImportto callincrementParentJobCounterson error, ensuring parent counters are updated - Removed
throw errorin error handler to prevent Lambda crashes and allow proper status propagation - This fix completes the Step Functions error handling started in v1.0.18, ensuring
SendTaskFailureis properly triggered - See ImportQueueEventHandler Error Handling for details
- Previously, when a child import job failed with errors like
1.0.18 (2026-01-10)
Bug Fixes
- import: Add
SendTaskFailuresupport toImportStatusHandlerfor proper Step Functions error handling- Previously, when an import job failed, the Step Function would wait indefinitely because only
SendTaskSuccesswas implemented - Now the handler properly sends
SendTaskFailurewhen a job fails, allowing Step Functions to handle errors correctly - Added
sendTaskFailure()method to sendSendTaskFailureCommand - Handler now processes both
COMPLETEDandFAILEDstatuses for CSV import jobs - See ImportStatusHandler API for details
- Previously, when an import job failed, the Step Function would wait indefinitely because only
1.0.17 (2026-01-08)
Bug Fixes
- master: Fix
masterTypeCodecomparison inMasterDataService.search()- Changed from partial match (contains) to exact match forsettingCodesearch parameter (See Details) - cli: Stabilize AbstractRunner tests by removing setTimeout to fix flaky CI failures
Security
- Fix security vulnerabilities in dependencies: jws (HMAC signature verification issue), nodemailer (DoS vulnerability)
Dependencies
- Bump validator from 13.15.20 to 13.15.26
- Bump @modelcontextprotocol/sdk from 1.25.1 to 1.25.2
Documentation
- Update README files for all packages with comprehensive API references and usage examples
- Fix
createTenantGroupparameter name in tenant package README - Update Japanese guide links to official documentation
1.0.16 (2025-12-31)
Bug Fixes
- cli: Add cleanup for test-generated files and update .gitignore
- master, directory, task, cli: Improve error messages for better clarity
Features
- Include __s3Key in attributes for import creation
- Zip mode provide table name
- Add optional s3Key to CreateImportDto
1.0.15 (2025-12-31)
Bug Fixes
- ui-setting: Improve error messages for better clarity
- mcp-server: Use MBC_PROJECT_PATH for ERROR_CATALOG.md lookup
1.0.14 (2025-12-29)
Features
- mcp-server: Add MCP server package for AI tool integration
Documentation
- Add comprehensive error message catalog
- Add JSDoc comments to core interfaces
- Add operational documentation (FAQ, troubleshooting, security)
- Add AI-friendly documentation files
1.0.13 (2025-12-26)
Features
- Enhance CreateZipImportDto and ZipImportQueueEventHandler
1.0.12 (2025-12-23)
Bug Fixes
- Merge tenant attributes in TenantService
1.0.11 (2025-12-22)
Bug Fixes
- Handle unknown source IP in SequencesService
1.0.10 (2025-11-28)
Bug Fixes
- Fix createTenantGroup method in TenantService
1.0.9 (2025-11-26)
Bug Fixes
- Remove callback parameter from Lambda handler for Node.js 24 compatibility
1.0.8 (2025-11-17)
Security
- Bump jws dependency for security fix
1.0.7 (2025-11-07)
Security
- Bump validator dependency in examples
- Bump js-yaml dependency for security fix
1.0.6 (2025-11-05)
Features
- master: Add tenantCode support to MasterDataCreateDto and update service logic
1.0.5 (2025-11-04)
Features
- master: Enhance master settings with tenantCode support in DTOs and service logic
1.0.4 (2025-10-29)
Features
- core: Add configurable request body size limit to bootstrap and environment validation
- master: Add bulk creation endpoints for master data and settings
Dependencies
- Bump validator from 13.11.0/13.12.0 to 13.15.20
- Bump multer from 1.4.4-lts.1 to 2.0.2 and @nestjs/platform-express from 10.4.4 to 10.4.20
- Bump axios from 1.7.7 to 1.13.1 in CLI templates
1.0.3 (2025-10-23)
Features
- master: Add bulk creation endpoints for master data and settings, enabling batch operations for improved efficiency
1.0.2 (2025-10-16)
Features
- survey: Add survey template API for managing survey templates
Dependencies
- Bump @nestjs/common from 10.3.0 to 10.4.16 in /examples/master
- Bump multer from 1.4.4-lts.1 to 2.0.2 and @nestjs/platform-express from 10.4.15 to 10.4.20 in /examples/seq
- Bump @nestjs/cli from 10.4.5 to 11.0.10 and inquirer from 8.2.6 to 8.2.7
1.0.1 (2025-09-19)
Features
- import: Add zip mode support for import module, enabling compressed file imports
1.0.0 (2025-09-18)
Highlights
- First stable production release
- Based on beta version 0.1.74
Beta Releases (0.1.x)
0.1.75-beta.0
Bug Fixes
- import: Add
SendTaskFailuresupport toImportStatusHandlerfor proper Step Functions error handling- Previously, when an import job failed, the Step Function would wait indefinitely because only
SendTaskSuccesswas implemented - Now the handler properly sends
SendTaskFailurewhen a job fails, allowing Step Functions to handle errors correctly - Added
sendTaskFailure()method to sendSendTaskFailureCommand - Handler now processes both
COMPLETEDandFAILEDstatuses for CSV import jobs - See ImportStatusHandler API for details
- Previously, when an import job failed, the Step Function would wait indefinitely because only
0.1.74-beta.0 (2025-08-25)
Features
- Import module implementation
- Infrastructure updates for import module
- Local infrastructure updates for import module
0.1.73-beta.0 (2025-07-31)
Bug Fixes
- master: Fixed package installation issue
0.1.72-beta.0 (2025-07-24)
Features
- Added case-insensitive search for master data and settings
0.1.71-beta.0 (2025-07-18)
Bug Fixes
- Fixed core package test failures blocking CI
- Fixed GitHub workflow issues
- Handle Step Function name length limit
- StepFunctionService execution name length validation
Features
- CLI package comprehensive test enhancement
- Core package service unit test enhancement
- Implemented comprehensive unit tests for controllers
- Master package service unit test enhancement
- Sequence service test enhancement
- Task service unit test enhancement
- Implemented missing service unit tests
- Implemented unit tests for high-priority packages
0.1.70-beta.0 (2025-07-14)
Bug Fixes
- master: Fixed master-setting unit test
- Updated package version
Features
- master: Added copy to tenant functionality
0.1.69-beta.0 (2025-07-07)
Bug Fixes
- master: Updated unit test
Features
- master: Added Prisma option
0.1.68-beta.0 (2025-07-01)
Bug Fixes
- Fixed build lib CI
- Updated import template master data module
Features
- Added template master API
0.1.67-beta.0 (2025-06-10)
Features
- Enhanced EmailService to support attachments
0.1.65-beta.0 (2025-05-19)
Bug Fixes
- Fixed empty AppSync URL issue
- Fixed test AppSync URL
Features
- Added second AppSync support
0.1.58-beta.0 (2025-04-24)
Bug Fixes
- Fixed get format sequence from master data item
0.1.55-beta.0 (2025-02-14)
Features
- Updated template to use Node 20 runtime
0.1.53-beta.0 (2025-02-12)
Features
- Added queue and Step Function for task processing
- Task processing by Step Function
0.1.51-beta.0 (2025-01-17)
Bug Fixes
- Corrected description text
Features
- Added logger
- Added schematic description
- Added schematic for generating controllers
- Added schematic for generating dto, service, entity
- Added schematic for generating module
0.1.50-beta.0 (2025-01-14)
Bug Fixes
- Fixed serialize helper entity field processing
Features
- Added serialize helper functions for internal/external structure conversion
Related Documentation
- Migration Guide v1.8.0 - Upgrade guide for v1.8.0 (master key rules, access control and copy)
- Migration Guide v1.7.0 - Upgrade guide for v1.7.0 (command admission conditions)
- Migration Guide v1.6.0 - Upgrade guide for v1.6.0 (Node.js 22)
- Migration Guide v1.3.0 - Upgrade guide for v1.3.0 (nodemailer v8)
- Migration Guide v1.2.0 - Upgrade guide for v1.2.0 (publishSync null return value)
- Migration Guide v1.1.0 - Upgrade guide for v1.1.0 (TENANT_COMMON, tenant code normalization)
- Version Conflict Guide - Handling version conflicts in upgrades
- Web Changelog - Release notes for master-web and survey-web frontend packages