Migration Guide: v1.8.0
This guide helps you upgrade from v1.7.x to v1.8.0. Version 1.8.0 changes only the master and survey-template packages. It adds opt-in access control for master data (the controllerAuth guard and a per-system access resolver), and it changes some behavior for every application that uses the master package: key validation, master copy, the unified bulk endpoint and the task parent route.
Release Date
2026-11-15
Changes Summary
| Change | Impact | Action Required |
|---|---|---|
# and @ rejected in every key segment | All apps. Requests with such codes, user IDs or group IDs fail with 400; existing rows with @ in their key are no longer reachable through the API | Check integrations; find and re-create affected rows |
| Setting and data rows changed only through their own routes | All apps that update or delete rows by pk/sk | Use /api/master-setting for setting rows and /api/master-data for data rows |
| Master copy reads the source tenant and copies sequences | All apps that use master copy | Review target sequences before copying |
Master copy requires system_admin | Apps that set controllerAuth or register a resolver | Give copy operators system_admin in the custom:roles claim |
POST /api/master-bulk upserts settings before data | All apps that use the unified bulk endpoint | Do not rely on the request being atomic |
GET /api/tasks/sfn-task-parent prefers the custom:tenant claim | Clients that sent a different tenant in x-tenant-code | Send requests for the caller's own tenant |
Update omitting settingValue, name or seq | All apps | None. Omitted fields are now kept |
MySQL search fix and databaseProvider option | Apps on MySQL | Drop local patches; set databaseProvider if detection fails |
controllerAuth, systemId and @MasterAccessResolver() (opt-in) | None unless enabled | Optional: follow Adopt Access Control |
Project template: an empty controllerAuth object | New projects only | Configure roles for master writes |
Pre-Migration Checklist
- The project already runs on v1.7.x and Node.js 22 (see the v1.7.0 migration guide)
- You know which integrations create master settings, master data, or user and group settings, and what values they use as codes, user IDs and group IDs
- You know whether your application calls master copy or
POST /api/master-bulk
Step 1: Update Dependencies
npm install \
@mbc-cqrs-serverless/core@^1.8.0 \
@mbc-cqrs-serverless/tenant@^1.8.0 \
@mbc-cqrs-serverless/master@^1.8.0 \
@mbc-cqrs-serverless/sequence@^1.8.0 \
@mbc-cqrs-serverless/task@^1.8.0 \
@mbc-cqrs-serverless/cli@^1.8.0
If you use the survey template package, update @mbc-cqrs-serverless/survey-template to ^1.8.0 as well.
Step 2: Check Key Segments
Every key segment is now validated. A value that is empty or contains # or @ is rejected with 400:
| Value | Where it is checked |
|---|---|
Setting code | Every setting create and upsert (common, tenant, group, user and bulk), and getSetting (GET /api/master-setting/:code). MASTER_SETTING is also rejected |
Master data settingCode | Data create, upsert, both bulk endpoints and MasterDataService.list (GET /api/master-data). MASTER_SETTING is also rejected |
Master data code | Data create, upsert and bulk |
userId / groupId | Group and user settings (POST /api/master-setting with a group or user target) |
Sort key with @ | PATCH/DELETE /api/master-setting/:pk/:sk and PUT/DELETE /api/master-data/:pk/:sk |
Why @: the command service treats @ as the version separator of a sort key. In 1.7.0 core cut a sort key at its last @, so:
- A value with one
@, such as an e-mail address used as auserIdor code, was silently stored under a truncated, different key. - A code with two or more
@(for exampleX@Y@Z) could store a row whose key still contains@(for exampleMASTER_SETTING#X@Y).
Why #: # separates key segments, so a code such as USER#u1#S1 built the key of another row, here a user's personal setting.
@ in their keyRows already stored with @ in their sort key can no longer be read, updated or deleted through the master API. Find them and re-create them under a valid key:
- DynamoDB: scan the master data table (not the command table, whose sort keys end with the version suffix) for items whose
skcontains@. - RDS: query the master table for rows whose
skcontains@.
Create a new setting or data row with a valid code, move the values over, and soft-delete or remove the old row directly in the database if you no longer need it. Also check rows written under a truncated key, for example a user setting stored for the part of an e-mail address before the last @.
Master data rows already stored with # in their code stay readable and can still be updated or deleted by key through /api/master-data/:pk/:sk, but a create or upsert that sends such a code is rejected.
Change integrations that generate codes, user IDs or group IDs with # or @, for example by using the Cognito sub instead of an e-mail address as the userId.
Step 3: Use the Right Route for Updates and Deletes
Setting rows and data rows are now changed only through their own routes:
| Route | Accepts | Rejects with 400 |
|---|---|---|
PATCH/DELETE /api/master-setting/:pk/:sk | MASTER_SETTING#<code>, plus group and user keys such as MASTER_SETTING#USER#u1#S1 | Data keys |
PUT/DELETE /api/master-data/:pk/:sk | Data keys <settingCode>#<code> | MASTER_SETTING#... keys |
The same rule applies to MasterSettingService.updateSetting/deleteSetting and MasterDataService.update/delete.
Step 4: Review Master Copy
Two fixes change the result of master copy for every application:
- Copy now reads data from the source setting's tenant. It used to read from a hard-coded
meltectenant. - Copy now copies sequences. 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.
Copy is also restricted:
- With
controllerAuthset,POST /api/master-setting/copyrequiressystem_adminregardless ofcontrollerAuth.write. - With a resolver registered,
MasterSettingService.copyrequiressystem_adminand a write grant whosesystemIdandsettingCodeare both*. A resolver that givessystem_adminnarrower grants blocks copy. - For copy,
system_adminmust come from thecustom:rolesclaim. Group-derived roles do not count.
Step 5: Do Not Rely on Bulk Atomicity
POST /api/master-bulk now upserts the settings first and the data rows after, so a data row can use a setting created in the same request. The keys of every item are validated before the first write.
With a resolver registered, the access checks of the data items run after the settings have been written. A data item the caller may not write fails the request with 403 and leaves the settings of the same request written. Split settings and data into separate requests if you need to know exactly what was written, and make retries idempotent (the endpoint upserts).
Step 6: Check Other Behavior Changes
- Task parent route:
GET /api/tasks/sfn-task-parentnow takes the tenant from thecustom:tenantclaim first, then fromx-tenant-code. It used to read acustom:tenant_codeclaim that nobody sets, so it always used the header. - Partial updates: a setting update that omits
settingValueno longer clears the setting's attributes, one that omitsnamekeeps the name, and a data update that omitsseqkeeps it. - Reserved attribute: a
__systemIdkey sent by a client inattributesis always removed. Responses go throughtoPublicRow, so a row stored earlier with a client-planted__systemIdreturns that value as a top-levelsystemId. - New route and fields:
GET /api/master-accessis added when the controllers are enabled, and the DTOs acceptsystemIdandincludeCommon. Without a resolver,systemIdis ignored. - MySQL: list searches now work on MySQL. Remove any patch that removed
mode: 'insensitive'from the dist files (for example withpatch-package). The database is detected from the Prisma client; setdatabaseProviderinMasterModule.registerorSurveyTemplateModule.register(or theirregisterAsync) if a startup warning says it could not be detected. See Database Provider.
Adopt Access Control (Optional)
Applications that set neither controllerAuth nor a resolver can stop after Step 6. To protect the built-in routes and scope master data per system, follow the rollout order below. See Master: Access Control and the framework guide Master data access control and per-system sync.
- Set
controllerAuthonMasterModule. Even an empty object turns the guard on: reads need a login, writes needsystem_admin. See Controller Authorization. - Add the RDS column: add a nullable
system_idcolumn to the PrismaMastermodel and writesystemId: getSystemId(cmd)in both thecreateandupdateof your RDS handler, then run the migration and deploy.update-scheme.tsdoes not change an existing schema or handler. See RDSsystem_idColumn. - Upgrade the frontend package, then register the resolver with
@MasterAccessResolver(). With a resolver registered and nosystemIdfield on the PrismaMastermodel, the application refuses to start. - Pass
invokeContextfrom server-side code that calls the master services, orskipAccessCheck: truefor trusted internal work. With a resolver registered, calls withoutinvokeContextare denied, including reads. - Tag existing data with
MasterSettingService.assignSystem. Untagged rows count asshared.
Also note, 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. See Include Common Tenant Rows.
With registerAsync, pass commonTenantCode, databaseProvider and controllerAuth statically. The static values override the ones the factory returns, even when the static value is undefined.
With controllerAuth, a caller whose token has no custom:tenant claim and who names the common tenant in x-tenant-code may get 403 when commonTenantCode is not listed in the COMMON_TENANT_CODES environment variable, because the tenant-override check of the base guard reads that variable rather than the module option. If you change commonTenantCode, add the same value to COMMON_TENANT_CODES.
Project Templates (New Projects Only)
| File | Before | After (v1.8.0) |
|---|---|---|
src/master/master.module.ts | No controllerAuth | An empty controllerAuth object: master writes need system_admin |
prisma/schema.prisma (Master model) | - | Nullable systemId mapped to system_id, with an index on tenantCode and systemId |
src/master/handler/master-rds.handler.ts | - | Writes systemId: getSystemId(cmd) |
Existing projects are not changed.
Step 7: Run Tests and Deploy
npm run test:cov
Support
If you encounter issues during migration:
Related Documentation
- Changelog v1.8.0 - v1.8.0 release notes
- Master - Master access control, key rules and module options
- Survey Template -
databaseProvideroption - Master data access control and per-system sync - Framework guide