@vsaas/loopback 12.1.0 → 12.2.0

package/docs/application-guide.md

@@ -0,0 +1,1110 @@
+# Application Guide
+
+This guide shows how to build LoopBack 3 style applications on top of the
+`@vsaas/*` forks in this monorepo using the promise-capable APIs provided by
+the packages.
+
+## Package roles
+
+- `@vsaas/loopback`: application factory, REST middleware, built-in models,
+  ACL integration, and remote method helpers
+- `@vsaas/loopback-boot`: loads datasources, models, mixins, components, and
+  boot scripts from a conventional app layout
+- `@vsaas/loopback-datasource-juggler`: model definitions, relations,
+  persistence, validation, and LoopBack filters
+- `@vsaas/remoting`: the remoting layer behind REST endpoints and custom remote
+  methods
+- `@vsaas/loopback-component-storage`: optional filesystem and S3-compatible
+  storage component
+- `@vsaas/loopback-softdelete-mixin4`: optional soft-delete mixin
+
+## Bootstrap an application
+
+`@vsaas/loopback-boot` is promise-capable, so the normal app bootstrap can use
+`async/await` directly.
+
+```js
+const loopback = require('@vsaas/loopback');
+const boot = require('@vsaas/loopback-boot');
+
+async function createApp() {
+  const app = loopback();
+
+  await boot(app, __dirname);
+
+  app.use('/api', loopback.rest());
+  return app;
+}
+
+module.exports = createApp;
+```
+
+Applications using two-factor authentication or authentication rate limiting
+must initialize authentication security after boot has connected all models
+and before the process starts listening:
+
+```js
+async function createApp() {
+  const app = loopback();
+
+  await boot(app, __dirname);
+  await app.initializeAuthenticationSecurity();
+
+  app.use('/api', loopback.rest());
+  return app;
+}
+
+createApp()
+  .then((app) => app.listen(3000))
+  .catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+```
+
+The initializer is idempotent and supports both Promise and callback forms.
+Authentication configured on a `User` model fails closed with
+`AUTHENTICATION_SECURITY_UNAVAILABLE` until initialization succeeds.
+Applications using only general rate limiting call
+`app.initializeRateLimiting()` at the same point instead.
+
+## General rate limiting
+
+See [Rate limiting](./rate-limiting.md) for the complete option reference,
+duration units, remote and programmatic rule contracts, error behavior,
+cleanup, and key rotation. This section is a compact application example.
+
+Configure infrastructure once per application. Subject values are HMACed
+before persistence; provide at least 32 bytes of random key material.
+
+```js
+app.set('rateLimit', {
+  limits: {
+    maxCostPerConsume: 100000,
+    maxBatchEntries: 1000,
+  },
+  subjectKeyrings: {
+    default: {
+      currentKeyId: 'v1',
+      keys: {
+        v1: process.env.RATE_LIMIT_HMAC_KEY_V1,
+      },
+    },
+  },
+  stores: {
+    api: {
+      provider: 'persisted-model',
+      model: 'RateLimitState',
+      namespace: 'my-api-production',
+    },
+  },
+});
+```
+
+`RateLimitState` must be attached to a shared durable datasource and configured
+as `public: false`. The memory connector is rejected unless
+`allowMemory: true` is explicitly set for tests. A Redis provider is not
+bundled; applications can register another provider before initialization with
+`app.registerRateLimitProvider(name, factory)`.
+
+The bundled provider is the persisted-model MVP. Redis delivery is explicitly
+outside the bundled release scope; deployments that require Redis must supply
+and integration-test a provider implementing the same atomic store contract.
+At startup, the persisted provider runs a short create/update/stale-update/delete
+probe and refuses readiness when the connector does not provide conditional
+compare-and-set semantics.
+
+Named programmatic rules can derive the limit, time window, subject, and cost
+from domain context without knowing anything about persistence:
+
+```js
+app.rateLimiter.defineRule({
+  id: 'sensor-data-write',
+  algorithm: 'fixed-window',
+  store: 'api',
+  subjectKeyring: 'default',
+  bucket: 'sensor-data-write',
+  onStoreError: 'deny',
+
+  subject({ sensor }) {
+    return {
+      namespace: 'my-api-production',
+      scope: 'sensor',
+      subjectType: 'sensor',
+      canonicalValue: String(sensor.id),
+    };
+  },
+
+  async limit({ sensor }) {
+    const policy = await resolveSensorPolicy(sensor);
+    if (!policy.enabled) return null;
+    return {
+      limit: policy.maxDataPoints,
+      windowMs: policy.windowMs,
+      blockDurationMs: policy.windowMs,
+      revision: String(policy.version),
+    };
+  },
+
+  cost({ dataPoints }) {
+    return dataPoints.length;
+  },
+});
+```
+
+An individual upload and a bulk `/Data` endpoint should use the same rule,
+bucket, and sensor subject. For a validated, deduplicated batch:
+
+```js
+const decisions = await app.rateLimiter.consumeBatch(
+  'sensor-data-write',
+  sensorGroups.map((group) => ({
+    entryId: group.sensorId,
+    context: {
+      sensor: group.sensor,
+      dataPoints: group.data,
+    },
+  })),
+);
+```
+
+Repeated sensor IDs are grouped into one atomic cost. Results retain input
+order. One denied sensor does not roll back or deny unrelated sensor groups.
+Validate and deduplicate data before calculating cost.
+
+Remote methods can use named static policies:
+
+```js
+app.set('rateLimitPolicies', {
+  faceSearch: {
+    policyId: 'face-search',
+    policyVersion: '1',
+    algorithm: 'fixed-window',
+    maxAttempts: 3,
+    observationWindow: 60,
+    blockDuration: 60,
+    stateTtl: 3600,
+  },
+});
+
+Face.remoteMethod('search', {
+  accepts: [],
+  returns: { arg: 'result', type: 'object', root: true },
+  http: { verb: 'post' },
+  rateLimit: {
+    policy: 'faceSearch',
+    store: 'api',
+    subjectKeyring: 'default',
+    onStoreError: 'deny',
+  },
+});
+```
+
+For credential, tenant, source, or resource rules, register a resolver before
+initialization and reference its name in `rateLimit.resolver`. It receives the
+model, logical method name, normalized arguments, request, access token, and
+`req.ip`; it returns one or more fully resolved rules. Returning several rules
+composes them without allowing a later result to overwrite an earlier denial.
+
+HTTP denials use `429 RATE_LIMITED`, `Retry-After`, and
+`Cache-Control: no-store`. Store failures use `503 RATE_LIMIT_UNAVAILABLE`.
+Programmatic callers receive the same typed errors.
+
+Use `app.cleanupRateLimitStates()` from a scheduled job to remove expired
+PersistedModel state. When rotating the subject HMAC, add the new key, make it
+current, retain old keys for at least the longest state TTL, and remove them
+only after old state expires. Changing namespace, store, policy semantics, or
+policy version is a coordinated migration, not a hot configuration change.
+Static rules and named remote policies are snapshotted during registration or
+startup. A dynamic rule must change its `revision` whenever its effective
+limit, window, block duration, or state TTL changes; reusing a revision with a
+different fingerprint fails closed.
+
+## Two-factor authentication
+
+See [Two-factor authentication](./two-factor-authentication.md) for the complete
+configuration reference, authentication rate-limit defaults, endpoint
+workflows, errors, cleanup, and key rotation. This section is a compact
+application example.
+
+Two-factor settings belong to each concrete `User` model. Supported modes are:
+
+- setting absent: legacy behavior;
+- `disabled`: installation mode, allowed only with no enabled credentials;
+- `enroll-and-verify`: enrollment and verification enabled;
+- `verify-only`: safe rollback that stops enrollment but continues enforcing
+  existing credentials.
+
+```js
+SecureUser.settings.twoFactor = {
+  mode: 'enroll-and-verify',
+  issuer: 'Example',
+  challengeTtl: 300,
+  verificationLeaseTtl: 30,
+  enrollmentTtl: 600,
+  maxAttempts: 5,
+  maxClockSkewSteps: 1,
+  totp: {
+    algorithm: 'SHA1',
+    digits: 6,
+    period: 30,
+    secretBytes: 20,
+  },
+  recoveryCodeCount: 10,
+  recoveryCodeBytes: 16,
+  encryption: {
+    currentKeyId: 'v1',
+    keys: { v1: process.env.TWO_FACTOR_ENCRYPTION_KEY_V1 },
+  },
+  recoveryCodeHmac: {
+    currentKeyId: 'v1',
+    keys: { v1: process.env.TWO_FACTOR_RECOVERY_HMAC_KEY_V1 },
+  },
+  principalBindingHmac: {
+    currentKeyId: 'v1',
+    keys: { v1: process.env.TWO_FACTOR_BINDING_HMAC_KEY_V1 },
+  },
+};
+```
+
+The encryption key must decode to exactly 32 bytes. HMAC keys must contain at
+least 32 bytes and the recovery/binding keys must be distinct.
+`TwoFactorCredential`, `TwoFactorChallenge`, and
+`TwoFactorRecoveryCode` must be attached to a durable datasource as private
+models. The framework encrypts TOTP secrets using AES-256-GCM, stores recovery
+codes only as HMAC-derived IDs, binds challenges to the current password hash,
+and prevents TOTP/recovery replay with conditional updates.
+
+Provision the private schemas before enabling traffic. For existing
+datasources, run the application's normal migration process for
+`RateLimitState`, `TwoFactorCredential`, `TwoFactorChallenge`, and
+`TwoFactorRecoveryCode`; do not rely on runtime automigration in production.
+The database must contain the unique
+`TwoFactorCredential(principalType, principalId, provider)` index and the
+primary/unique IDs declared by the models. The initializer checks that the
+unique credential index is present in model metadata, but connector-independent
+code cannot prove that an out-of-band database migration was actually applied.
+Verify the physical indexes in deployment validation.
+
+Authentication rate limiting remains independent of 2FA and can use an
+application store:
+
+```js
+SecureUser.settings.authenticationRateLimit = {
+  enabled: true,
+  store: 'api',
+  subjectHash: {
+    currentKeyId: 'v1',
+    keys: { v1: process.env.AUTH_RATE_LIMIT_HMAC_KEY_V1 },
+  },
+  policies: {
+    password: {
+      policyId: 'authentication-password',
+      policyVersion: '1',
+      maxFailedAttempts: 5,
+      observationWindow: 900,
+      blockDuration: 60,
+      strategy: 'exponential',
+      multiplier: 2,
+      maxBlockDuration: 3600,
+      backoffResetAfter: 86400,
+      stateTtl: 604800,
+    },
+  },
+};
+```
+
+Password-only login stays unchanged for users without an enabled credential.
+For enrolled users, `User.login` accepts optional `twoFactorMethod` and
+`twoFactorCode`. A valid password without a code returns
+`403 TWO_FACTOR_REQUIRED` with a short-lived opaque `challengeId`; complete it
+at `POST /Users/two-factor/verify`. Enrollment and recovery management are:
+
+- `POST /Users/two-factor/setup`;
+- `POST /Users/two-factor/confirm`;
+- `POST /Users/two-factor/recovery-codes`;
+- `POST /Users/two-factor/disable`.
+
+The management endpoints require an authenticated token and reauthentication.
+Enrollment secrets and recovery codes are returned once. Sensitive responses
+and challenges use `Cache-Control: no-store`. Rate-limit responses use
+`429 AUTHENTICATION_RATE_LIMITED`; a failed limiter store or unready security
+initializer fails closed.
+
+Override `getTwoFactorPrincipalBindingMaterial` when password verification
+lives outside `User.password`, and override
+`validateTwoFactorLoginPrincipal` for custom disabled/locked account state.
+Neither hook may derive its result from request-controlled data.
+
+Run `app.cleanupAuthenticationSecurity()` periodically. It recovers expired
+verification leases only after claiming them with CAS, reconciles known issued
+tokens before releasing recovery-code reservations, retains ambiguous
+reservations in quarantine, removes non-active recovery sets, and deletes
+orphaned or retention-expired credentials. Monitor
+`authenticationSecurityCleanupError` and any challenge left in
+`token_revocation_pending`; a row without a durable issued-token identifier
+requires operator reconciliation and is intentionally not released.
+
+Rotate AES keys by deploying the added key everywhere, selecting it as current,
+and running `app.rotateAuthenticationSecurityEncryption({batchSize: 100})`
+until every model reports zero remaining credentials and live challenges. The
+framework migration uses compare-and-set and is safe to rerun. Retire the old
+key only after no live envelope references it and terminal challenge retention
+has elapsed. Existing recovery
+codes cannot be re-HMACed; regenerate their sets before removing an old
+recovery HMAC key. Keep old binding keys for at least the challenge TTL plus
+lease and rollout margin. A safe rollback uses `verify-only`, never
+password-only bypass.
+
+Typical app layout:
+
+```text
+server/
+  server.js
+  model-config.json
+  datasources.json
+  boot/
+common/
+  models/
+    book.json
+    book.js
+```
+
+## Define models
+
+The most common style is a boot-loaded model made of:
+
+1. a JSON definition in `common/models/*.json`
+2. a model module in `common/models/*.js`
+3. an entry in `server/model-config.json`
+
+### File-based models
+
+`server/model-config.json`
+
+```json
+{
+  "_meta": {
+    "sources": [
+      "@vsaas/loopback/common/models",
+      "@vsaas/loopback/server/models",
+      "../common/models",
+      "./models"
+    ],
+    "mixins": [
+      "@vsaas/loopback/common/mixins",
+      "@vsaas/loopback/server/mixins",
+      "../common/mixins",
+      "./mixins"
+    ]
+  },
+  "Book": {
+    "dataSource": "db",
+    "public": true
+  }
+}
+```
+
+`common/models/book.json`
+
+```json
+{
+  "name": "Book",
+  "base": "PersistedModel",
+  "plural": "Books",
+  "idInjection": true,
+  "options": {
+    "validateUpsert": true
+  },
+  "properties": {
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "isbn": {
+      "type": "string",
+      "required": true
+    },
+    "status": {
+      "type": "string",
+      "default": "draft"
+    },
+    "metadata": {
+      "type": "object"
+    }
+  },
+  "relations": {
+    "author": {
+      "type": "belongsTo",
+      "model": "Author"
+    },
+    "chapters": {
+      "type": "hasMany",
+      "model": "Chapter"
+    }
+  }
+}
+```
+
+`common/models/book.js`
+
+```js
+module.exports = function (Book) {
+  Book.validatePromise(
+    'isbn',
+    async function () {
+      const duplicate = await Book.findOne({
+        where: {
+          isbn: this.isbn,
+          id: { neq: this.id },
+        },
+      });
+
+      if (duplicate) {
+        throw new Error('ISBN already exists');
+      }
+    },
+    { message: 'ISBN must be unique' },
+  );
+};
+```
+
+Notes:
+
+- `public: true` exposes the model through REST. Use `public: false` for
+  internal models and service-only models.
+- `base` controls inheritance. If you omit it, the registry falls back to
+  `PersistedModel`.
+- `options.validateUpsert` is useful when you rely on `upsert` and want normal
+  model validation to run there too.
+
+### Programmatic models
+
+For tests, dynamic models, or embedded types, creating models in code is often
+the clearest option.
+
+```js
+const Address = app.registry.createModel('Address', {
+  street: String,
+  city: String,
+  zipCode: String,
+});
+
+const Customer = app.registry.createModel(
+  'Customer',
+  {
+    name: String,
+    address: { type: Address },
+    tags: [String],
+  },
+  { strict: true },
+);
+
+app.model(Customer, {
+  dataSource: 'db',
+  public: true,
+});
+```
+
+You can also create models directly from a datasource:
+
+```js
+const AuditLog = app.dataSources.db.createModel('AuditLog', {
+  action: String,
+  actorId: String,
+  createdAt: Date,
+});
+```
+
+## Define endpoints
+
+### Built-in CRUD endpoints
+
+When a model is public and attached to a datasource, LoopBack exposes its CRUD
+surface automatically. Relations expose their own REST routes too.
+
+Examples for a public `Book` model:
+
+- `GET /api/Books`
+- `GET /api/Books/:id`
+- `POST /api/Books`
+- `PATCH /api/Books/:id`
+- `DELETE /api/Books/:id`
+- `GET /api/Books/:id/chapters`
+- `POST /api/Books/:id/chapters`
+
+### Custom static remote methods
+
+Custom endpoints are defined in the model module with an implementation plus
+`remoteMethod(...)`.
+
+```js
+module.exports = function (Book) {
+  Book.summary = async function (filter, options) {
+    const books = await Book.find(filter || {});
+
+    return {
+      count: books.length,
+      requestedBy: options?.accessToken?.userId ?? null,
+    };
+  };
+
+  Book.remoteMethod('summary', {
+    http: { verb: 'get', path: '/summary' },
+    accepts: [
+      { arg: 'filter', type: 'object' },
+      { arg: 'options', type: 'object', http: 'optionsFromRequest' },
+    ],
+    returns: { arg: 'result', type: 'object', root: true },
+  });
+};
+```
+
+### Custom instance remote methods
+
+Use the `prototype.` prefix when you want an endpoint on a model instance.
+
+```js
+module.exports = function (Book) {
+  Book.prototype.publish = async function (options) {
+    await this.updateAttributes({
+      status: 'published',
+      publishedBy: options?.accessToken?.userId ?? null,
+      publishedAt: new Date(),
+    });
+
+    return this;
+  };
+
+  Book.remoteMethod('prototype.publish', {
+    http: { verb: 'post', path: '/publish' },
+    accepts: [{ arg: 'options', type: 'object', http: 'optionsFromRequest' }],
+    returns: { arg: 'result', type: 'Book', root: true },
+  });
+};
+```
+
+With the example above, the endpoint is exposed at:
+
+- `POST /api/Books/:id/publish`
+
+### Remote hooks
+
+Remote hooks can be synchronous, callback-based, or promise-returning. In
+promise-first applications, returning a value or a promise keeps the code much
+cleaner than chaining `next(...)`.
+
+```js
+module.exports = function (Book) {
+  Book.beforeRemote('summary', async (ctx) => {
+    const filter = ctx.args.filter || {};
+    const limit = Math.min(filter.limit || 50, 100);
+
+    ctx.args.filter = {
+      ...filter,
+      limit,
+    };
+  });
+
+  Book.afterRemote('summary', async (ctx) => {
+    ctx.result.generatedAt = new Date().toISOString();
+  });
+};
+```
+
+### Access the request context as `options`
+
+LoopBack supports a special HTTP mapping named `optionsFromRequest`. By
+default, it injects `accessToken`, and you can enrich it from the remoting
+context.
+
+```js
+module.exports = function (Book) {
+  Book.createOptionsFromRemotingContext = function (ctx) {
+    return {
+      accessToken: ctx.req?.accessToken ?? null,
+      requestId: ctx.req?.headers['x-request-id'] ?? null,
+    };
+  };
+};
+```
+
+## ACLs
+
+ACLs are declared in the model JSON under `acls`.
+
+```json
+{
+  "acls": [
+    {
+      "principalType": "ROLE",
+      "principalId": "$everyone",
+      "permission": "DENY"
+    },
+    {
+      "principalType": "ROLE",
+      "principalId": "authenticated",
+      "permission": "ALLOW",
+      "property": ["find", "findById", "count"]
+    },
+    {
+      "principalType": "ROLE",
+      "principalId": "editor",
+      "permission": "ALLOW",
+      "property": ["create", "prototype.publish", "deleteById"]
+    },
+    {
+      "principalType": "ROLE",
+      "principalId": "$owner",
+      "permission": "ALLOW",
+      "accessType": "*"
+    }
+  ]
+}
+```
+
+Common ACL patterns:
+
+- deny everything for `$everyone`, then allow the exact roles or methods you
+  want to expose
+- use `property` for exact method names such as `find`, `deleteById`,
+  `prototype.publish`, or relation methods like `__get__chapters`
+- use `accessType` when you want broader rules such as `READ`, `WRITE`,
+  `EXECUTE`, or `*`
+- keep service models private with `public: false` in `model-config.json`
+
+If you need custom roles, register them in a boot script with
+`Role.registerResolver(...)` and keep the model ACL JSON focused on the role
+names themselves.
+
+## Filters
+
+LoopBack filters are plain objects passed to methods such as `find`,
+`findOne`, `count`, relation scopes, and custom remote methods.
+
+This section focuses on the filter shapes confirmed against
+`@vsaas/loopback-connector-mongodb`.
+
+The supported top-level keys are:
+
+- `where`
+- `fields`
+- `order`
+- `limit`
+- `skip`
+- `include`
+
+### `where`
+
+```js
+const filter = {
+  where: {
+    status: 'published',
+    priority: { gte: 3 },
+    or: [{ archived: false }, { archived: { exists: false } }],
+  },
+};
+
+const books = await Book.find(filter);
+```
+
+Common `where` operators supported by the MongoDB connector:
+
+- equality: `{ status: 'published' }`
+- `neq`: `{ status: { neq: 'archived' } }`
+- `gt`, `gte`, `lt`, `lte`: `{ priority: { gte: 3 } }`
+- `exists`: `{ archivedAt: { exists: true } }`
+- `inq`: `{ status: { inq: ['draft', 'published'] } }`
+- `nin`: `{ status: { nin: ['deleted', 'archived'] } }`
+- `between`: `{ createdAt: { between: [fromDate, toDate] } }`
+- `like`: `{ title: { like: '^LoopBack' } }`
+- `nlike`: `{ title: { nlike: '^Internal' } }`
+- `regexp`: `{ email: { regexp: /@example\\.com$/i } }`
+- boolean composition: `{ and: [ ... ] }`, `{ or: [ ... ] }`,
+  `{ nor: [ ... ] }`
+
+Examples:
+
+```js
+const filter = {
+  where: {
+    status: { inq: ['draft', 'published'] },
+    category: { nin: ['internal', 'deleted'] },
+    createdAt: {
+      between: [new Date('2026-01-01T00:00:00.000Z'), new Date('2026-12-31T23:59:59.999Z')],
+    },
+  },
+};
+```
+
+```js
+const filter = {
+  where: {
+    and: [{ title: { like: 'LoopBack' } }, { authorName: { nlike: '^deprecated-' } }],
+  },
+};
+```
+
+Notes:
+
+- `inq` and `nin` require arrays
+- `between` requires an array with exactly two values
+- `like` and `nlike` accept either a string pattern or a `RegExp`
+- when `like` or `nlike` receives a string, `options` is passed as the regexp
+  flags argument used to build `new RegExp(pattern, options)`
+- the most common `options` value is `'i'` for case-insensitive matching
+- when you pass a `RegExp` value instead, put the flags in the regexp itself
+  and omit `options`
+
+Example with `options`:
+
+```js
+const filter = {
+  where: {
+    title: {
+      like: '^loopback',
+      options: 'i',
+    },
+  },
+};
+```
+
+Important:
+
+- `like`, `nlike`, and `regexp` become MongoDB regex queries (`$regex` or
+  `$not`)
+- do not recommend regex-based queries by default; they can be expensive and
+  can easily defeat normal index usage depending on the pattern
+- only use them when you are fully sure about data volume, selectivity, and
+  indexing strategy
+- avoid the `g` flag; MongoDB does not respect it for regex queries
+
+The MongoDB connector in this monorepo enables nested-property queries, so dot
+paths work in `where` too:
+
+```js
+const users = await User.find({
+  where: {
+    'address.city': 'San Jose',
+    'address.tags.tag': 'business',
+  },
+});
+```
+
+Confirmed examples for MongoDB-style nested queries:
+
+- `'address.city': 'San Jose'`
+- `'address.city': { gt: 'San' }`
+- `'friends.name': { regexp: /^Ringo/ }`
+- `'address.tags.tag': 'business'`
+
+### `include`
+
+Use `include` to fetch related models, and `scope` to filter the included data.
+
+```js
+const posts = await Post.find({
+  include: [
+    {
+      relation: 'author',
+      scope: { fields: ['name'] },
+    },
+  ],
+});
+
+const users = await User.find({
+  include: [
+    {
+      relation: 'posts',
+      scope: {
+        where: { published: true },
+        order: 'createdAt DESC',
+        limit: 5,
+      },
+    },
+  ],
+});
+```
+
+### `fields`
+
+Use `fields` when you want a partial projection. It accepts an array, a string,
+or an object map.
+
+```js
+const devices = await Device.find({
+  fields: ['name', 'status'],
+});
+```
+
+```js
+const books = await Book.find({
+  fields: {
+    title: true,
+    status: true,
+  },
+});
+```
+
+For embedded documents, the MongoDB connector also supports dot-path
+projection:
+
+```js
+const devices = await Device.find({
+  fields: ['name', '_config.address'],
+});
+```
+
+That produces a MongoDB projection equivalent to:
+
+```js
+{
+  name: 1,
+  '_config.address': 1,
+}
+```
+
+and is the right way to request only specific fields from embedded models or
+nested objects.
+
+### `order` (sorting)
+
+LoopBack uses the key `order`, not `sort`.
+
+```js
+const books = await Book.find({
+  order: ['publishedAt DESC', 'title ASC'],
+});
+```
+
+You can also pass a single string:
+
+```js
+const books = await Book.find({
+  order: 'publishedAt DESC, title ASC',
+});
+```
+
+The MongoDB connector in this monorepo also supports dot paths in `order`:
+
+```js
+const users = await User.find({
+  where: { 'address.state': 'CA' },
+  order: 'address.city DESC',
+});
+```
+
+### `limit` and `skip`
+
+```js
+const page = await Book.find({
+  where: { status: 'published' },
+  order: 'publishedAt DESC',
+  limit: 20,
+  skip: 40,
+});
+```
+
+Notes:
+
+- `limit` must be a positive integer
+- `skip` must be a non-negative integer
+
+### Filters over REST
+
+For `GET` requests, the filter is sent as one JSON-encoded `filter` query
+parameter.
+
+```bash
+curl --get 'http://localhost:3000/api/Books' \
+  --data-urlencode 'filter={"where":{"status":"published"},"include":[{"relation":"author","scope":{"fields":["name"]}}],"order":"publishedAt DESC","limit":10}'
+```
+
+TypeScript example using the native `fetch` API:
+
+```ts
+type LoopBackFilter = {
+  where?: Record<string, unknown>;
+  include?: unknown[];
+  order?: string | string[];
+  limit?: number;
+  skip?: number;
+  fields?: string[] | Record<string, boolean>;
+};
+
+const filter: LoopBackFilter = {
+  where: { status: 'published' },
+  include: [{ relation: 'author', scope: { fields: ['name'] } }],
+  order: 'publishedAt DESC',
+  limit: 10,
+};
+
+const params = new URLSearchParams({
+  filter: JSON.stringify(filter),
+});
+
+const response = await fetch(`http://localhost:3000/api/Books?${params.toString()}`);
+
+const books = await response.json();
+```
+
+The important part is sending `filter` as one JSON-encoded query parameter.
+
+When you define a custom `POST` endpoint, you can also accept the filter in the
+body instead of encoding it in the query string.
+
+## Validation and async/await
+
+The modernized packages are callback-compatible, but the application-facing
+CRUD methods can be used directly with promises.
+
+```js
+const created = await Book.create({
+  title: 'Designing APIs',
+  isbn: '978-1-23456-789-0',
+});
+
+const found = await Book.find({
+  where: { id: created.id },
+});
+
+await created.updateAttributes({
+  status: 'published',
+});
+```
+
+### `validatePromise`
+
+`validatePromise(...)` lets you write async validation logic without callback
+plumbing inside the validator itself.
+
+```js
+module.exports = function (Book) {
+  Book.validatePromise(
+    'isbn',
+    async function (options) {
+      if (!this.isbn?.startsWith('978-') && !this.isbn?.startsWith('979-')) {
+        throw new Error('ISBN must start with 978- or 979-');
+      }
+
+      if (options?.allowDuplicateIsbn === true) {
+        return;
+      }
+
+      const duplicate = await Book.findOne({
+        where: {
+          isbn: this.isbn,
+          id: { neq: this.id },
+        },
+      });
+
+      if (duplicate) {
+        throw new Error('ISBN already exists');
+      }
+    },
+    { message: 'ISBN is invalid' },
+  );
+};
+```
+
+Persisted model methods such as `create`, `save`, `updateAttributes`,
+`replaceOrCreate`, and `patchOrCreate` trigger model validation automatically,
+so the normal pattern is to validate through the same `await` flow you use for
+data persistence.
+
+```js
+try {
+  await Book.create({
+    title: 'Bad example',
+    isbn: 'invalid',
+  });
+} catch (error) {
+  if (error.statusCode === 422) {
+    console.error(error.details.messages);
+  }
+  throw error;
+}
+```
+
+If you manually call `isValid()` with async validators configured, keep in mind
+that the validation entrypoint itself remains callback-oriented. In
+promise-first codebases, persisting with `await` is usually the cleanest way to
+run `validatePromise` rules.
+
+## Optional packages
+
+### `@vsaas/loopback-component-storage`
+
+Storage datasources are commonly mounted as private service models. A typical
+filesystem setup looks like this:
+
+`server/datasources.json`
+
+```json
+{
+  "AssetStorage": {
+    "name": "AssetStorage",
+    "connector": "@vsaas/loopback-component-storage",
+    "provider": "filesystem",
+    "root": "/var/lib/app/Asset"
+  }
+}
+```
+
+`server/model-config.json`
+
+```json
+{
+  "AssetStorageService": {
+    "dataSource": "AssetStorage",
+    "public": false
+  }
+}
+```
+
+For S3-compatible backends, the same package supports `provider: "s3"` and
+`provider: "amazon"`, plus signed URL configuration via `signedUrl`.
+
+See the package README for the full provider matrix:
+[loopback-component-storage/README.md](../../loopback-component-storage/README.md).
+
+### `@vsaas/loopback-softdelete-mixin4`
+
+Register the mixin directory in `_meta.mixins` and enable it per model.
+
+`server/model-config.json`
+
+```json
+{
+  "_meta": {
+    "mixins": ["../node_modules/@vsaas/loopback-softdelete-mixin4", "../common/mixins", "./mixins"]
+  }
+}
+```
+
+`common/models/book.json`
+
+```json
+{
+  "mixins": {
+    "SoftDelete": true
+  }
+}
+```
+
+By default, soft-deleted rows are excluded. To include them in a query, pass
+`deleted: true` at the top level of the filter:
+
+```js
+const books = await Book.find({
+  where: { status: 'archived' },
+  deleted: true,
+});
+```
+
+If your application enables soft delete broadly, you can opt out on a specific
+model with `"SoftDelete": false`.
+
+See the package README for supported mixin options such as `deletedAt`,
+`deletedById`, `scrub`, and `index`:
+[loopback-softdelete-mixin/README.md](../../loopback-softdelete-mixin/README.md).