Skip to main content

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​

ChangeImpactAction Required
# and @ rejected in every key segmentAll 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 APICheck integrations; find and re-create affected rows
Setting and data rows changed only through their own routesAll apps that update or delete rows by pk/skUse /api/master-setting for setting rows and /api/master-data for data rows
Master copy reads the source tenant and copies sequencesAll apps that use master copyReview target sequences before copying
Master copy requires system_adminApps that set controllerAuth or register a resolverGive copy operators system_admin in the custom:roles claim
POST /api/master-bulk upserts settings before dataAll apps that use the unified bulk endpointDo not rely on the request being atomic
GET /api/tasks/sfn-task-parent prefers the custom:tenant claimClients that sent a different tenant in x-tenant-codeSend requests for the caller's own tenant
Update omitting settingValue, name or seqAll appsNone. Omitted fields are now kept
MySQL search fix and databaseProvider optionApps on MySQLDrop local patches; set databaseProvider if detection fails
controllerAuth, systemId and @MasterAccessResolver() (opt-in)None unless enabledOptional: follow Adopt Access Control
Project template: an empty controllerAuth objectNew projects onlyConfigure 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:

ValueWhere it is checked
Setting codeEvery setting create and upsert (common, tenant, group, user and bulk), and getSetting (GET /api/master-setting/:code). MASTER_SETTING is also rejected
Master data settingCodeData create, upsert, both bulk endpoints and MasterDataService.list (GET /api/master-data). MASTER_SETTING is also rejected
Master data codeData create, upsert and bulk
userId / groupIdGroup 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 a userId or code, was silently stored under a truncated, different key.
  • A code with two or more @ (for example X@Y@Z) could store a row whose key still contains @ (for example MASTER_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.

Existing rows with @ in their key

Rows 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 sk contains @.
  • RDS: query the master table for rows whose sk contains @.

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:

RouteAcceptsRejects with 400
PATCH/DELETE /api/master-setting/:pk/:skMASTER_SETTING#<code>, plus group and user keys such as MASTER_SETTING#USER#u1#S1Data keys
PUT/DELETE /api/master-data/:pk/:skData 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 meltec tenant.
  • 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 controllerAuth set, POST /api/master-setting/copy requires system_admin regardless of controllerAuth.write.
  • With a resolver registered, MasterSettingService.copy requires system_admin and a write grant whose systemId and settingCode are both *. A resolver that gives system_admin narrower grants blocks copy.
  • For copy, system_admin must come from the custom:roles claim. 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.

Not atomic

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-parent now takes the tenant from the custom:tenant claim first, then from x-tenant-code. It used to read a custom:tenant_code claim that nobody sets, so it always used the header.
  • Partial updates: a setting update that omits settingValue no longer clears the setting's attributes, one that omits name keeps the name, and a data update that omits seq keeps it.
  • Reserved attribute: a __systemId key sent by a client in attributes is always removed. Responses go through toPublicRow, so a row stored earlier with a client-planted __systemId returns that value as a top-level systemId.
  • New route and fields: GET /api/master-access is added when the controllers are enabled, and the DTOs accept systemId and includeCommon. Without a resolver, systemId is ignored.
  • MySQL: list searches now work on MySQL. Remove any patch that removed mode: 'insensitive' from the dist files (for example with patch-package). The database is detected from the Prisma client; set databaseProvider in MasterModule.register or SurveyTemplateModule.register (or their registerAsync) 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.

  1. Set controllerAuth on MasterModule. Even an empty object turns the guard on: reads need a login, writes need system_admin. See Controller Authorization.
  2. Add the RDS column: add a nullable system_id column to the Prisma Master model and write systemId: getSystemId(cmd) in both the create and update of your RDS handler, then run the migration and deploy. update-scheme.ts does not change an existing schema or handler. See RDS system_id Column.
  3. Upgrade the frontend package, then register the resolver with @MasterAccessResolver(). With a resolver registered and no systemId field on the Prisma Master model, the application refuses to start.
  4. Pass invokeContext from server-side code that calls the master services, or skipAccessCheck: true for trusted internal work. With a resolver registered, calls without invokeContext are denied, including reads.
  5. Tag existing data with MasterSettingService.assignSystem. Untagged rows count as shared.

Also note, with a resolver registered:

  • Creating a tenant-level override of a common setting that has no systemId treats that setting as shared: a requested systemId other than shared is rejected with 400, write access to shared is required, and the override stores no systemId.
  • includeCommon is bounded: a master data list with includeCommon requires settingCode unless 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.

Possible 403 for header-selected common tenant

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)​

FileBeforeAfter (v1.8.0)
src/master/master.module.tsNo controllerAuthAn 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: