Common code useful for express/mongo/redis/gae applications.
Version 16 changed the module type to NodeNext and the target type to ES2021. This should be appropriate for any library using TypeScript 4.5+ and NodeJS 18+.
In version 15.0.0 we updated to required mongoose 8 rather than mongoose 6 that had previously been required. Client projects should update their mongoose dependency to ^8, and go through these two migration guides:
https://mongoosejs.com/docs/migrating_to_7.html https://mongoosejs.com/docs/migrating_to_8.html
Breaking changes:
- See the migration guides for mongoose.
One notable change to mongoose is that strictQuery has been defaulted to false
in mongoose 7. Client projects may wish to add:
mongoose.set('strictQuery', true);
immediately after creating their connection to preserve existing behavior.
In version 14.8 we added basic support for child routes for resource controllers. These routes will be attached as subroutes of the resource, invoked only if the parent resource exists and permissions check pass. See ResourceChildRoute.
Breaking changes:
- ValidationError is now a subclass of ApiError and now takes a
message as the first parameter. Yay for a standard error hierarchy
and standardized API exceptions!
Breaking changes:
- SimpleModelController.mapDomainToResource now takes a second parameter
of type VerifiedUserInfo, allowing the implementation to do role/permission-
based conversions. You probably don't have to do anything to support this
unless you are calling the method explicitly.
Breaking changes:
- VerifiedUserInfo.verifiedGrants is no more. If you are updating from
a version prior to 10.x, lucky you, because it only existed in 10.x.
In version 10.1 we started looking for the 'X-Direqt-Roles' header from IAM in proxied requests.
Potentially breaking changes:
- VerifiedUserInfo.verifiedGrants is deprecated (already!). We've added
a new required `verifiedRoles` property to take its place. This isn't
strictly a breaking change as VerifiedUserInfo should always be
readonly to clients, but test cases might need to be updated.
Version 10.x introduces support for service role definitions that define the security policy for resource requests via SimpleModelController. Previously, any non-standard permission mapping had to be handled on an ad-hoc basic by controllers (typically by overriding SimpleModelController.hasPermission). With the new service role definition support, non-standard permissions can be assigned to user requests based on the service roles attached to that user.
Breaking changes:
- SimpleModelController constructor has a new required argument `name`.
This argument is of the form { service: string, resource: string } where
`name.service` should be the high-level service ('iam', 'chat',
'gallery', etc) and `name.resource` should be the resource name as
exposed to the clients (e.g., 'chatApplication', 'gallery').
Other notable changes:
- SimpleModelController constructor has a new optional argument
`options.roleDefinitions`. All resources in a service should share the
same role definitions, which allow the role names provided by IAM to be
mapped to resource-specific permissions.
- VerifiedUserInfo has a new property `verifiedGrants`. This holds
information about role grants given to the requesting user. The
property is populated from the secure HTTP headers provided by IAM to
the service ('X-Direqt-Grants' header). Note especially that this field
will NOT hold information about basic roles (MemberRole/SystemRole);
that information remains in the `verifiedRole` field.
Internal changes include the creation of a ResourcePermissionService to factor out logic needed by the controller for determining permissions for requests.
The major update in 9.x is the introduction of resource schemas, which allows classes derived from SimpleModelController to specify all resource properties and policies for how they may be used.
When migrating to schemas, keep these things in mind:
- `options.readOnly` and `options.permittedQueryKeys` are now redundant in
the SimpleModelController constructor. Rather than specifying values there,
you should mark the corresponding properties as `readonly` or `queryable`,
respectively, in the provided schema.
- You should not override mapInputToResourceXxx if you have provided a
resource schema. The base class methods will perform the mappings for you
automatically.
Resource schemas are currently optional, and existing classes should be unaffected.
Breaking changes:
- SimpleModelController.permittedQueryKeys has been removed. If you have a class
derived from SimpleModelController that had defined an override of
`permittedQueryKeys`, you should remove the override and intead pass the
array to the constructor in the `options` argument.
(Note that the 7.x branch didn't stablize until 7.3, and there are breaking changes between 7.0 and 7.3; since no project updated to any version of 7.x before 7.3, we ignore those changes and just focus on projects migrating from 6.x to 7.3+).
Breaking changes:
- SimpleModelController.mapInternalToPublic has been removed. If you have a class derived from SimpleModelController, you should now override `mapDomainToResource` instead. Be sure to do a global search on any project updating to 7.x, because without the override keyword on your derived class implementation (you should use "noImplicitOverride" in tsconfig!) you may not notice this!
The primary update in this major version is the addition in SimpleModelController of specific types for "create" and "update" params that may be independent from the public resource type. This is implemented with two additional generic types on SimpleModelController which, if not specified, fallback to the existing behavior.
In addition, the pipeline for processing create and update operations has become more structured to aid in ensuring we protect against invalid/malicious inputs. The input pipeline is now:
1. HTTP request received;
2. body, params, and query string are all sanitized via middleware to remove known attack vectors (e.g., mongo-specific injection attacks);
3. untyped inputs are converted to expected resource-specific type with overridable `mapInputToResourceXxx` method;
4. deep validation implemented with overridable `validateResourceUpdate` method.
Controllers are now encouraged to supply four generic types (domain model, resource model, create resource model, and update resource model), and implement the following mapping functions:
mapInputToResourceCreate
- parse input given to a create operation
mapInputToResourceUpdate
- parse input given to an update operation
mapResourceCreateToDomain
- map input for a create operation to the internal domain type used by the associated service
mapResourceUpdateToDomain
- map input for an update operation to the internal domain type used by the associated service
mapDomainToResource
- map the output from the associated service to the public resource type exposed by the controller
In addition, many controllers will want to implement:
validateResourceCreate
- perform additional deep checks on input parameters given to a create operation.
validateResourceUpdate
- perform additional deep checks on input parameters given to an update operation.
For the most part, any controller currently working with 6.x should work without modification. NOTE HOWEVER THE REMOVAL OF mapInternalToPublic referenced above.
NOTE ALSO that the signature of sterilizeEntity has changed, which may require any controller that had overridden it to tweak their definition. (This method is now deprecated in favor of performing any sterilization in parseResourceXxx).
Finally, note that, if you override mapDomainToResource, the id and network properties will no longer automatically be scrubbed from your resources as they were when mapInternalToPublic was in use. You are expected to perform any scrubbing appropriate if you override these methods.
These methods have been deprecated:
`sterilizeEntity` - we now perform mongo-specific sterilization of body, params, and query strings in middleware that runs for all routes. This method remains in order to filter out properties beginning with underscores, but derived classes should no longer override this method.
For example implementations, see the WidgetController2 class defined in the test cases in SimpleModelController.test.ts.
There are several breaking changes in the update to 6.x.
Each standard method on resources (get, list, create, update, delete), as well as each custom action, has an associated permission. By default, permissions are assigned to users based on the MemberRole in the VerifiedUserInfo.verifiedRole supplied by IAM in a way that closely mimics the existing behavior.
owner, editor, admin: ['get', 'list', 'create', 'update', delete] viewer: ['get', 'list']
Note, however, that permissions for custom actions are not granted to any users by default. See notes below.
Any classes that derive from ModelService (or SimpleModelService), or SimpleModelController, will need to rename these methods:
`getOne` -> `get`
`getAll` -> `list`
`del` -> `delete
The behavior of these methods is unchanged.
Previously, custom actions could be defined on SimpleModelControllers by supplying the action name as a key:
class MyController extends SimpleModelController<> {
actions = {
'bark': async () => null,
'wag': async () => null,
}
}
Custom actions must now be defined as an array of ResourceAction objects :
class MyController extends SimpleModelController<> {
actions = [{
name: 'bark',
handler: async () => null,
}, {
name: 'wag',
handler: async () => null,
}]
}
When an action handlers (ResourceActions installed with SimpleModelController.actions) wants to return an error to the caller, it should throw an exception of type ActionError, specifying the HTTP status and message to return. InvalidActionState has been removed.
As part of the integration of permission-based authorization checks into the SimpleModelController, invoking a custom action now requires the caller to posess a specific named permission that, by default, has the same name as the action. For example, an action named 'bark' will require that the caller have the '.bark' permission.
By default, the legacy MemberRole roles are mapped to a set of basic permissions that will not include any custom permissions. To enable a custom action for these roles, your override of SimpleModelController must override hasPermission:
class MyController extends SimpleModelController<> {
// /<resource>/:id/bark will require 'bark' permission
actions = [{
name: 'bark',
handler: async () => null,
}];
hasPermission(verb: string, userInfo: VerifiedUserInfo): boolean {
if (verb === 'bark') {
// allow 'admin' role the '<resource>.bark' permission
return userInfo.verifiedRole === MemberRole.admin;
}
return super.hasPermission(verb, userInfo);
}
}
For custom actions that are intended to be callable for users with a standard permission like 'get' or 'update', you can avoid overridding hasPermission and simply provide a permission attribute when defining the action:
// /<resource>/:id/bark will require 'update' permission
actions = [{
name: 'bark',
permission: 'update',
handler: async () => null,
}];
This object should only ever be generated by IAM or trusted IAM client code, so no changes should be required. Some test cases, however, may need to be updated to include a verifiedRole where previously it had been optional.
The mongoose peerDependency is now set to the 6.x branch. There are a handful of breaking changes that you will have to confront when making the necessary update to any client service.
See https://mongoosejs.com/docs/migrating_to_6.html
Copyright (c) 2021 Direqt Inc.