@antelopejs/interface-database-decorators 0.1.11 → 0.2.0

package/docs/3.table-modifiers.md

@@ -1,14 +1,18 @@
-# Table Modifiers
+---
+title: Table modifiers
+description: Reference for the encryption, hashing, localization, and auto-date modifiers, the scrypt hash format, and the classes and events for writing a custom modifier.
+mode: reference
+---
 
-Table modifiers transform field values as they are stored in and retrieved from the database. They enable transparent encryption, hashing, localization, and custom data transformations. Add modifiers to a table class using the `Table.with()` method.
+A table modifier transforms a field's value on its way into a row and on its way out. The built-in modifiers encrypt, hash, or localize a field, or set a timestamp. Add a modifier's mixin to a table class with `Table.with()`, then mark each field with the modifier's decorator.
 
-## Built-in Modifiers
+## Built-in modifiers
 
-### EncryptionModifier
+### `EncryptionModifier`
 
-The `EncryptionModifier` encrypts field values before storing them and decrypts them on retrieval. Both operations happen transparently.
+The `EncryptionModifier` encrypts a field's value when the value is assigned and decrypts it when the field is read.
 
-The default `aes-256-gcm` algorithm requires a key of exactly 32 bytes. `secretKey` is passed to Node's cipher as a UTF-8 string, without hex or base64 decoding. Supply a high-entropy, 32-byte UTF-8 value from a secret manager, keep it stable for existing ciphertext, and fail startup if it is missing or invalid; a 64-character hex encoding is not a 32-byte key for this API.
+The default `aes-256-gcm` algorithm needs a key of exactly 32 bytes. `secretKey` goes to Node's cipher as a UTF-8 string, without hex or base64 decoding. Supply a high-entropy, 32-byte UTF-8 value from a secret manager, keep it stable while ciphertext exists, and fail startup if it is missing or invalid. A 64-character hex encoding is 64 bytes for this API, not a 32-byte key.
 
 ```ts docs-check
 import {
@@ -41,13 +45,13 @@ class UserCredentials extends Table.with(EncryptionModifier) {
 }
 ```
 
-#### How It Works
+#### How it works
 
-- Data is encrypted using the specified algorithm before database insertion.
-- A random initialization vector (IV) is generated for each write.
-- For authenticated encryption algorithms (e.g., `aes-256-gcm`), an auth tag is stored alongside the ciphertext.
-- On retrieval, the data is automatically decrypted.
-- Date objects are restored as `Date` instances, but the encoder uses `toUTCString()`, which drops milliseconds. Encrypted dates round-trip only to whole-second precision.
+- An assignment encodes the value as JSON and encrypts it with the configured algorithm. The row stores `[ciphertext, iv, authTag]`, each in base64.
+- Each write generates a random initialization vector (IV).
+- An authenticated algorithm, such as `aes-256-gcm`, also stores its auth tag. Other algorithms store no tag.
+- A read decrypts the value.
+- A `Date` comes back as a `Date` instance. The encoder writes it with `toUTCString()`, which drops milliseconds, so an encrypted date keeps whole-second precision only.
 
 #### Options
 
@@ -57,9 +61,9 @@ class UserCredentials extends Table.with(EncryptionModifier) {
 | `algorithm` | `string` | `"aes-256-gcm"` | Encryption algorithm.                |
 | `ivSize`    | `number` | `16`            | Initialization vector size in bytes. |
 
-### HashModifier
+### `HashModifier`
 
-The `HashModifier` stores a salted one-way hash of field values. Unlike encryption, hashing is irreversible -- you cannot retrieve the original value. Its default SHA-256 hash is fast, not a password-hardening function; use a dedicated password hashing library for production credentials.
+The `HashModifier` stores a salted one-way hash of a field's value. A hash cannot be reversed, so the original value cannot be read back. By default the field stores a scrypt hash, a memory-hard function made for passwords.
 
 ```typescript
 import {
@@ -73,43 +77,68 @@ class User extends Table.with(HashModifier) {
   @Field("string")
   declare email: string;
 
-  @Hashed({ algorithm: "sha256" })
+  @Hashed()
   @Field("string")
   declare password: string;
 
-  verifyPassword(plainPassword: string): boolean {
-    return this.testHash("password", plainPassword);
+  verifyPassword(plainPassword: string): Promise<boolean> {
+    return this.testHashAsync("password", plainPassword);
   }
 }
 ```
 
-#### How It Works
+#### How it works
 
-- A random salt is generated and stored in the field's metadata on first write.
-- The value is hashed with the salt using the specified algorithm.
-- The `testHash` method (added by the mixin) hashes a candidate value with the stored salt and compares the result.
+- The field hashes the value encoded as JSON, so `"secret"` is hashed as the text `"\"secret\""`.
+- Each write draws a random 16-byte salt and stores `$scrypt$ln=15,r=8,p=3$<salt>$<key>`. The salt and the 32-byte key are base64 without padding. `ln` is the base-2 logarithm of the scrypt cost N, so N is 32768. The string holds the parameters, the salt, and the key, so the cost can change later.
+- A write is synchronous, because a property setter cannot wait, and so are the conversions behind a model's `insert` and `update`. Each assignment blocks the event loop for one scrypt run, which uses 32 MiB (128 × N × r bytes).
+- Assigning the stored hash back to the field, or calling `lock` on a loaded row, keeps the hash as it is. Assigning `undefined` stores nothing.
+- `testHash` and `testHashAsync` read `ln`, `r`, `p`, the salt, and the key from the stored string. They derive a key of the stored key's length from the candidate and compare the two with `crypto.timingSafeEqual`, in constant time.
+- A stored scrypt string verifies only within these limits: `ln`, `r`, and `p` from 1 to 99, at most 128 MiB of memory, `p` at most 16, `ln` below 16 × `r`, and a salt and a key of 16 to 64 bytes each. A string outside them refuses every candidate.
+- On a field without an `algorithm`, a test spends one scrypt run whatever the row holds, a hash in another format or nothing included. The time of a refusal does not tell whether the row holds a current hash.
 
 #### Options
 
-| Option      | Type     | Default    | Description        |
-| ----------- | -------- | ---------- | ------------------ |
-| `algorithm` | `string` | `"sha256"` | Hashing algorithm. |
+| Option      | Type     | Default | Description                                                                                                                                                                        |
+| ----------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `algorithm` | `string` | none    | Digest to store instead of scrypt, any name `createHash` accepts. A digest is fast to guess, so use it only for non-secret fingerprints, never for credentials. See the next list. |
 
-`LocalizationModifier.fallbackLocaleOf(TableClass, field)` returns a field's `fallbackLocale`, or `undefined` when the field is not localized or declares none. Generated forms use it to require a value in that locale.
+A field with an `algorithm` stores the base64 digest of the row's salt followed by the JSON-encoded value. The salt is a random string that the first such write creates. The row keeps it in `_internal.meta.HashModifier.salt` and reuses it for every later write to its digest fields. A test of a digest field that holds a digest spends no scrypt run. The field still verifies a scrypt string it holds, with one scrypt run, and `isHashOutdated` never flags it, so a scrypt hash is never flagged for replacement by a weaker digest.
 
-#### Mixin Method
+#### Mixin methods
 
-The `HashModifier` mixin adds a `testHash` method to table instances:
+The `HashModifier` mixin adds these methods to table instances:
 
-```typescript
-testHash(field: string, value: unknown): boolean
+```typescript fragment
+testHash<This extends {}, F extends keyof This>(this: This, field: F, value: This[F]): unknown
+testHashAsync<This extends {}, F extends keyof This>(this: This, field: F, value: This[F]): Promise<boolean>
+isHashOutdated<This extends {}>(this: This, field: keyof This): boolean
+```
+
+- `testHashAsync` resolves whether `value` matches the stored hash. It runs scrypt on the thread pool, so use it on a server. It rejects with `Field <name> is not hashed` for a field without `@Hashed`.
+- `testHash` gives the same result and blocks the event loop while scrypt runs. Its declared return type is `unknown`. On a hashed field, the value is a boolean.
+- `isHashOutdated` returns whether the stored hash differs from what the field writes today, which is any stored string that does not start with `$scrypt$ln=15,r=8,p=3$`. It returns `false` when nothing is stored, and always on a field with an `algorithm`. It throws `Field <name> is not hashed` for a field without `@Hashed`.
+
+#### Upgrade stored hashes
+
+A row whose hash has another format still verifies. On a field without an `algorithm`, a string that is not a scrypt hash is tested as a salted SHA-256 digest, made with the salt in `_internal.meta.HashModifier.salt`, and `isHashOutdated` returns `true` for it. A scrypt hash of another cost verifies with its own parameters and is flagged too. To rewrite a flagged hash, assign the value after a successful test, because only then is the plaintext known:
+
+```typescript fragment
+if (await user.testHashAsync("password", password)) {
+  if (user.isHashOutdated("password")) {
+    user.password = password;
+    await userModel.update(user);
+  }
+}
 ```
 
-Returns `true` if `value`, when hashed, matches the stored hash for the given field.
+`userModel.update(user._id, { password })` rewrites the hash too. An update that leaves the hashed field out, by ID or with the whole row, keeps the stored hash.
 
-### LocalizationModifier
+To move a credential off `@Hashed({ algorithm: "sha256" })`, remove the option. Its rows keep verifying, and `isHashOutdated` flags them. A row written with another digest verifies only while the field declares that digest.
 
-The `LocalizationModifier` stores multiple language versions of a field value. Access a specific locale by calling `localize()` on the table instance.
+### `LocalizationModifier`
+
+The `LocalizationModifier` stores one value of a field per locale. To read or write a locale, call `localize()` on the table instance.
 
 ```typescript
 import {
@@ -133,9 +162,11 @@ class Product extends Table.with(LocalizationModifier) {
 }
 ```
 
+`LocalizationModifier.fallbackLocaleOf(TableClass, field)` returns a field's `fallbackLocale`, or `undefined` when the field is not localized or declares none. Generated forms use it to require a value in that locale.
+
 #### Usage
 
-```typescript
+```typescript fragment
 const product = new Product();
 product._id = "prod-123";
 product.price = 99.99;
@@ -149,30 +180,29 @@ product.localize("es").name = "Auriculares Premium";
 const spanish = product.localize("es");
 console.log(spanish.name); // "Auriculares Premium"
 
-// Fallback to default locale when translation is missing
+// Fall back to the default locale when a translation is missing
 const german = product.localize("de");
 console.log(german.name); // "Premium Headphones" (fallback)
 ```
 
-#### Wildcard Key
+#### Wildcard key
 
-The wildcard key `"*"` retrieves or sets all translations at once at runtime. `localize()` does not change the property's TypeScript type, so a field declared as `string` needs an explicit view for bulk access:
+The wildcard key `"*"` reads or writes all translations at once. `localize()` does not change the property's TypeScript type, so a field declared as `string` holds a record of texts by locale under `"*"`. Read that record as `unknown` and check it before use. Write it with `Object.assign`, which calls the field's setter:
 
-```typescript
+```typescript fragment
 // Get all translations
-const translations = product.localize("*") as unknown as {
-  name: Record<string, string>;
-};
-const allNames = translations.name;
+const allNames: unknown = product.localize("*").name;
 // { en: "Premium Headphones", fr: "Casque Premium", es: "Auriculares Premium" }
 
 // Set all translations
-translations.name = {
-  en: "Premium Headphones",
-  fr: "Casque Premium",
-  es: "Auriculares Premium",
-  de: "Premium-Kopfhoerer",
-};
+Object.assign(product.localize("*"), {
+  name: {
+    en: "Premium Headphones",
+    fr: "Casque Premium",
+    es: "Auriculares Premium",
+    de: "Premium-Kopfhoerer",
+  },
+});
 ```
 
 #### Options
@@ -181,23 +211,23 @@ translations.name = {
 | ---------------- | -------- | --------------------------------------------------------------------- |
 | `fallbackLocale` | `string` | Locale to use when the requested locale has no value or an empty one. |
 
-#### Mixin Method
+#### Mixin method
 
 The `LocalizationModifier` mixin adds a `localize` method:
 
-```typescript
-localize(locale: string, fields?: Array<keyof this>): this
+```typescript fragment
+localize<This extends { constructor: any }>(this: This, locale: string, fields?: Array<keyof This>): This
 ```
 
-`localize()` changes the active locale and returns the same object, not a locale-specific copy.
+`localize()` changes the active locale and returns the same object, not a copy for that locale.
 
 - **References share state.** `spanish`, `german`, and `product` above refer to one object. A later `localize()` call changes what all three references read.
-- **Fields can be restricted.** When you supply `fields`, only those fields are unlocked for the selected locale.
-- **Copy values before switching.** Save the values you need before changing locales, and do not share one instance between concurrent locale-specific operations.
+- **Fields can be restricted.** When you supply `fields`, only those fields switch to the selected locale.
+- **Copy values before switching.** Save the values you need before you change locales, and do not share one instance between concurrent operations on different locales.
 
-### AutoDateModifier
+### `AutoDateModifier`
 
-The `AutoDateModifier` automatically populates timestamp fields during insert and update operations. Use the `CreationTime` and `UpdateTime` decorators to mark fields.
+The `AutoDateModifier` sets timestamp fields on insert and update. Mark the fields with the `CreationTime` and `UpdateTime` decorators.
 
 ```typescript
 import {
@@ -217,15 +247,15 @@ class Article extends Table {
 }
 ```
 
-#### How It Works
+#### How it works
 
-- On insert, both `CreationTime` and `UpdateTime` fields are set to the current date.
-- On update, `UpdateTime` fields are refreshed while `CreationTime` fields are removed from the payload so the original creation date is preserved.
-- This is an event-only modifier: it does not transform stored values and does not require adding a mixin through `Table.with()`.
+- On insert, both `CreationTime` and `UpdateTime` fields get the current date.
+- On update, `UpdateTime` fields get the current date, and `CreationTime` fields are removed from the payload, so the stored creation date stays.
+- The modifier only handles events. It does not transform stored values and has no mixin, so the table class needs no `Table.with()`.
 
-## Combine Multiple Modifiers
+## Combine multiple modifiers
 
-Pass multiple modifier classes to `Table.with()`:
+Pass several modifier classes to `Table.with()`:
 
 ```typescript
 import {
@@ -266,11 +296,11 @@ class UserProfile extends Table.with(
 }
 ```
 
-## Create Custom Modifiers
+## Create custom modifiers
 
-### OneWayModifier
+### `OneWayModifier`
 
-A `OneWayModifier` transforms data in one direction (when writing to the database). Use it for irreversible transformations like hashing.
+A `OneWayModifier` transforms data in one direction, when a value is written. Use it for a transformation that cannot be reversed, such as hashing.
 
 ```typescript
 import {
@@ -311,18 +341,18 @@ const PrefixHashed = MakePropertyDecorator(
 );
 ```
 
-The generic parameters for `OneWayModifier<LockedType, Args, Meta, Options>` are:
+The generic parameters of `OneWayModifier<LockedType, Args, Meta, Options>` are:
 
-| Parameter    | Description                                          |
-| ------------ | ---------------------------------------------------- |
-| `LockedType` | The type stored in the database after transformation |
-| `Args`       | Additional arguments for `lock` and `test`           |
-| `Meta`       | Per-field metadata stored alongside the value        |
-| `Options`    | Configuration passed via the decorator               |
+| Parameter    | Description                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `LockedType` | The type stored in the database after the transformation.                                                |
+| `Args`       | Additional arguments for `lock` and `test`. Defaults to `[]`.                                            |
+| `Meta`       | The modifier's state for a row, kept in `_internal.meta.<modifier class name>` and shared by its fields. |
+| `Options`    | The configuration that the decorator passes to `attachModifier`.                                         |
 
-### TwoWayModifier
+### `TwoWayModifier`
 
-A `TwoWayModifier` extends `OneWayModifier` with an `unlock` method for reversible transformations like encryption:
+A `TwoWayModifier` extends `OneWayModifier` with an `unlock` method, for a transformation that can be reversed, such as encryption:
 
 ```ts docs-check
 import {
@@ -334,7 +364,7 @@ import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
 import type { ValueProxy } from "@antelopejs/interface-database";
 
 class Base64Modifier extends TwoWayModifier<
-  string | undefined,
+  unknown,
   [],
   {},
   { prefix?: string }
@@ -342,23 +372,23 @@ class Base64Modifier extends TwoWayModifier<
   public readonly autolock = true;
   public readonly autounlock = true;
 
-  public override lock(_locked: string | undefined, value: unknown) {
+  public override lock(_locked: unknown, value: unknown) {
     if (value === undefined) return undefined;
     const prefix = this.options.prefix || "b64-";
     return `${prefix}${Buffer.from(JSON.stringify(value)).toString("base64")}`;
   }
 
-  public override unlock(locked: string | undefined): unknown {
-    if (locked === undefined) return undefined;
+  public override unlock(locked: unknown): unknown {
+    if (typeof locked !== "string") return undefined;
     const prefix = this.options.prefix || "b64-";
     const encoded = locked.substring(prefix.length);
     return JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
   }
 
   public override unlockrequest(
-    data: ValueProxy<string | undefined>,
+    data: ValueProxy<unknown>,
   ): ValueProxy<unknown> {
-    return data.cast<unknown>();
+    return data;
   }
 
   [MixinSymbol] = class {};
@@ -376,11 +406,11 @@ const Base64Encoded = MakePropertyDecorator(
 );
 ```
 
-Base64 is encoding, not encryption. This example's `unlockrequest()` leaves the encoded value unchanged in database expressions; only instance reads decode it.
+Base64 is an encoding, not encryption. The example declares its `LockedType` as `unknown`, so `unlockrequest()` can return the stored value's proxy as it is. Database expressions therefore see the encoded value, and only instance reads decode it. `unlock` reads a stored value that is not a string as `undefined`.
 
-### ContainerModifier
+### `ContainerModifier`
 
-For modifiers that store multiple values in a key-value structure (like `LocalizationModifier`), extend `ContainerModifier`. It provides built-in support for the wildcard key `"*"` for bulk operations:
+A modifier that stores several values under keys, as `LocalizationModifier` does, extends `ContainerModifier`. Its `lock`, `unlock`, and `unlockrequest` take the key as their argument. `lock` and `unlock` treat the wildcard key `"*"` as the whole record:
 
 ```typescript
 import { ContainerModifier } from "@antelopejs/interface-database-decorators";
@@ -391,18 +421,18 @@ class MyContainerModifier extends ContainerModifier<{}, { fallback?: string }> {
 }
 ```
 
-## Modifier Events
+## Modifier events
 
-Modifiers can hook into the data lifecycle by implementing event handler methods. These methods are called during data conversion and database operations:
+A modifier hooks into a row's lifecycle through methods named after events. The engine calls each one with the modifier as `this`, then the table instance, the field name, and the event's arguments:
 
-| Event           | Triggered When                             |
-| --------------- | ------------------------------------------ |
-| `fromPlainData` | After converting plain data to an instance |
-| `toPlainData`   | After converting an instance to plain data |
-| `fromDatabase`  | After reading from the database            |
-| `toDatabase`    | Before writing to the database             |
-| `insert`        | Before inserting a new record              |
-| `update`        | Before updating an existing record         |
+| Event           | Triggered when                                                        |
+| --------------- | --------------------------------------------------------------------- |
+| `fromPlainData` | After plain data is converted to an instance.                         |
+| `toPlainData`   | After an instance is converted to plain data.                         |
+| `fromDatabase`  | After a stored record is converted to an instance, as reads do.       |
+| `toDatabase`    | When an instance is converted to the record to store, before a write. |
+| `insert`        | Before a model or a fixture inserts a new record.                     |
+| `update`        | Before a model updates an existing record.                            |
 
 ```typescript
 import {
@@ -411,15 +441,15 @@ import {
 } from "@antelopejs/interface-database-decorators";
 
 class TimestampModifier extends Modifier {
-  public insert(instance: any, field: string) {
-    if (field === "createdAt" && !instance[field]) {
-      instance[field] = new Date();
+  public insert<F extends string>(object: Partial<Record<F, Date>>, field: F) {
+    if (field === "createdAt" && !object[field]) {
+      object[field] = new Date();
     }
   }
 
-  public update(instance: any, field: string) {
+  public update<F extends string>(object: Partial<Record<F, Date>>, field: F) {
     if (field === "updatedAt") {
-      instance[field] = new Date();
+      object[field] = new Date();
     }
   }
 
@@ -427,4 +457,4 @@ class TimestampModifier extends Modifier {
 }
 ```
 
-Event-only modifiers (without `lock`/`unlock`) are valid and useful for side effects like logging, validation, or auto-populating fields.
+A modifier without `lock` and `unlock` only handles events. `attachModifier` then defines no accessor on the field, which keeps its plain value. Such a modifier fits side effects such as logging, validation, or filling in fields.