@futdevpro/fsm-dynamo 1.20.92 → 1.20.93

package/build-esm/_collections/utils/operation-authz.util.js

@@ -0,0 +1,136 @@
+import { DyFM_OperationAuth_Type } from '../../_enums/operation-auth.type-enum';
+import { DyFM_OperationContext_ControlModel } from '../../_models/control-models/operation-context.control-model';
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+/**
+ * The scope that grants EVERY operation (owner decision D-9, 2026-09-18: "legyen all scope").
+ *
+ * ⚠️ **What it means, stated plainly:** a key holding this scope passes every scope check — including the
+ * checks of operations that DO NOT EXIST YET. A capability added next month is granted to it automatically,
+ * with nobody re-approving. That is the deliberate trade of this decision: one token instead of a list.
+ *
+ * ⛔ It can not collide with a real scope: an operation scope always names a domain and an action
+ * (`note:read`), so no declared `apiKeyScope` can ever be this token.
+ */
+export const DyFM_operationAllScope = '*';
+/**
+ * Transport-independent authorization checks of an operation call (HP-DOPL MP-1.4).
+ *
+ * Two phases, because ownership needs the loaded entity:
+ * 1. `check` / `assert` — identity + API key scope, BEFORE the operation runs;
+ * 2. `checkOwnership` / `assertOwnership` — inside `run`, once the target entity is loaded.
+ *
+ * @example
+ * ```ts
+ * DyFM_OperationAuthz_Util.assert(operation, ctx);
+ * const task: Task = await loadTask(id);
+ * DyFM_OperationAuthz_Util.assertOwnership(operation, ctx, task);
+ * ```
+ */
+export class DyFM_OperationAuthz_Util {
+    /**
+     * Checks the identity and API key scope requirements of the operation.
+     * @param operation - the operation being called
+     * @param ctx - the call context built by the transport adapter
+     */
+    static check(operation, ctx) {
+        const issuerRequired = operation?.authz?.issuerRequired !== false;
+        const authKind = ctx?.authKind ?? DyFM_OperationAuth_Type.none;
+        // a missing identity is 401, the caller may retry with credentials
+        if (issuerRequired && (authKind === DyFM_OperationAuth_Type.none || !ctx?.issuer)) {
+            return DyFM_OperationAuthz_Util.deny('DyFM-OPZ-UNA', 401, `operation "${operation?.name}" requires an authenticated caller`, 'This operation needs an authenticated caller — send an API key or a token.');
+        }
+        // scopes only restrict API keys; a token call is not scope-limited
+        if (authKind !== DyFM_OperationAuth_Type.apiKey) {
+            return { allowed: true };
+        }
+        // legacy key (created before scopes): full access, but the adapter must surface the warning
+        if (DyFM_OperationContext_ControlModel.isLegacyApiKey(ctx)) {
+            return { allowed: true, warning: 'legacy-api-key' };
+        }
+        const requiredScope = operation?.authz?.apiKeyScope;
+        // a public operation without scope is reachable anonymously, so a scoped key must not be worse off
+        if (!requiredScope && !issuerRequired) {
+            return { allowed: true };
+        }
+        // least privilege: a scoped key can not reach a protected operation that belongs to no scope
+        if (!requiredScope) {
+            return DyFM_OperationAuthz_Util.deny('DyFM-OPZ-NSC', 403, `operation "${operation?.name}" declares no apiKeyScope, a scoped API key can not call it`, 'This operation can not be called with an API key. Call it with a user token.');
+        }
+        // the all-scope grants every operation (D-9); otherwise the match is EXACT — a scope is never a prefix
+        if (!DyFM_OperationAuthz_Util.grantsScope(ctx.apiKeyScopes, requiredScope)) {
+            return DyFM_OperationAuthz_Util.deny('DyFM-OPZ-SCP', 403, `API key lacks scope "${requiredScope}" for operation "${operation?.name}"`, `The API key is missing the "${requiredScope}" scope, which this operation needs. ` +
+                'Create a key that has it (an existing key\'s scopes can not be widened).');
+        }
+        return { allowed: true };
+    }
+    /**
+     * Same as `check`, but throws a coded `DyFM_Error` (with `status`) on denial.
+     * @returns the allowed result, so a `warning` can still be surfaced by the adapter
+     */
+    static assert(operation, ctx) {
+        return DyFM_OperationAuthz_Util.throwIfDenied(DyFM_OperationAuthz_Util.check(operation, ctx), operation, ctx);
+    }
+    /**
+     * Checks that the caller owns the loaded target entity, when the operation declares `authz.ownership`.
+     * @param operation - the operation being called
+     * @param ctx - the call context; its `clientUserId` is the owner identity (never `issuer`)
+     * @param target - the loaded entity the operation acts on
+     */
+    static checkOwnership(operation, ctx, target) {
+        const ownershipField = operation?.authz?.ownership;
+        // no ownership declared: nothing to check
+        if (!ownershipField) {
+            return { allowed: true };
+        }
+        // a declared ownership check without a caller identity must fail closed, not pass
+        if (!ctx?.clientUserId) {
+            return DyFM_OperationAuthz_Util.deny('DyFM-OPZ-OWN', 403, `operation "${operation?.name}" requires the caller's clientUserId for the ownership check`, 'This operation works on your own data, so it needs to know which user you are.');
+        }
+        const owner = target ? Reflect.get(target, ownershipField) : undefined;
+        // strict equality: an entity without owner is not owned by anybody
+        if (owner === undefined || owner === null || String(owner) !== ctx.clientUserId) {
+            return DyFM_OperationAuthz_Util.deny('DyFM-OPZ-OWN', 403, `caller does not own the target of operation "${operation?.name}" (field: ${ownershipField})`, 
+            // ⛔ the owner and the field name stay inside: the caller only learns that it is not theirs
+            'This item belongs to somebody else.');
+        }
+        return { allowed: true };
+    }
+    /** Same as `checkOwnership`, but throws a coded `DyFM_Error` (with `status`) on denial. */
+    static assertOwnership(operation, ctx, target) {
+        return DyFM_OperationAuthz_Util.throwIfDenied(DyFM_OperationAuthz_Util.checkOwnership(operation, ctx, target), operation, ctx);
+    }
+    /** Builds a denial result. */
+    /**
+     * Whether a key's scope list covers the required scope — either exactly, or through the all-scope (D-9).
+     *
+     * @param scopes - the scopes the key carries
+     * @param requiredScope - the scope the operation declares
+     */
+    static grantsScope(scopes, requiredScope) {
+        const held = scopes ?? [];
+        return held.includes(requiredScope) || held.includes(DyFM_operationAllScope);
+    }
+    static deny(errorCode, status, reason, userMessage) {
+        return {
+            allowed: false, errorCode: errorCode, status: status, reason: reason, userMessage: userMessage,
+        };
+    }
+    /** Converts a denial into a thrown `DyFM_Error`; the identity is logged by requestId only. */
+    static throwIfDenied(result, operation, ctx) {
+        if (result.allowed) {
+            return result;
+        }
+        throw new DyFM_Error({
+            errorCode: result.errorCode,
+            status: result.status,
+            message: `Operation authorization failed: ${result.reason}`,
+            // ⛔ the internal `message` never reaches the caller — this is the text written FOR them
+            userMessage: result.userMessage,
+            additionalContent: {
+                operation: operation?.name,
+                requestId: ctx?.requestId,
+                authKind: ctx?.authKind,
+            },
+        });
+    }
+}

package/build-esm/_collections/utils/operation-guardrails.util.js

@@ -0,0 +1,220 @@
+import { DyFM_OperationIfMatch_Type } from '../../_enums/operation-if-match.type-enum';
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_OperationPatchField_Type } from '../../_enums/operation-patch-field.type-enum';
+/**
+ * Transport-independent write guardrails of an operation (HP-DOPL MP-1.5, DMCP-009).
+ *
+ * Two phases, like the authorization:
+ * 1. `assertPreconditions` — before running (called by `DyFM_OperationRun_Util.execute`);
+ * 2. `assertIfMatch` / `filterPatch` — inside `run`, once the current entity is loaded.
+ *
+ * @example
+ * ```ts
+ * const task: Task = await loadTask(id);
+ * DyFM_OperationGuardrails_Util.assertIfMatch(op, ctx, DyFM_OperationGuardrails_Util.buildEtag(task.__v));
+ * const { patch } = DyFM_OperationGuardrails_Util.filterPatch(op, input);
+ * if (!ctx.dryRun) await saveTask(id, patch);
+ * ```
+ */
+export class DyFM_OperationGuardrails_Util {
+    /**
+     * Builds the etag of an entity from its document version (`__v`), as the organizer MCP does.
+     * @param version - the document version; a missing version counts as `0`
+     */
+    static buildEtag(version) {
+        return String(version || 0);
+    }
+    /**
+     * Checks what can be checked without the entity: dry-run support and the presence of a required `ifMatch`.
+     * @throws a coded `DyFM_Error` (400 `DyFM-OPG-DRY` · 428 `DyFM-OPG-IFM`)
+     */
+    static assertPreconditions(operation, ctx) {
+        // a caller asking for a dry run must never cause a real write
+        if (ctx?.dryRun === true && operation?.guardrails?.dryRun !== true) {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-DRY', status: 400, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}" does not support dryRun`,
+            });
+        }
+        // a required precondition that is missing: the caller must fetch the entity first
+        if (operation?.guardrails?.ifMatch === DyFM_OperationIfMatch_Type.required && !ctx?.ifMatch) {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-IFM', status: 428, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}" requires ifMatch (the etag of the entity)`,
+                details: { suggestion: 'Fetch the entity and send its current etag as ifMatch.' },
+            });
+        }
+    }
+    /**
+     * Compares the caller's `ifMatch` with the entity's current etag.
+     * @param currentEtag - the etag of the entity as loaded now
+     * @throws 409 `DyFM-OPG-CNF` on mismatch (and 428 when a required `ifMatch` is missing)
+     */
+    static assertIfMatch(operation, ctx, currentEtag) {
+        const mode = operation?.guardrails?.ifMatch ?? DyFM_OperationIfMatch_Type.none;
+        if (mode === DyFM_OperationIfMatch_Type.none) {
+            return;
+        }
+        // repeated here, so the check is complete even when run is called outside execute
+        if (!ctx?.ifMatch) {
+            if (mode === DyFM_OperationIfMatch_Type.required) {
+                throw DyFM_OperationGuardrails_Util.error({
+                    errorCode: 'DyFM-OPG-IFM', status: 428, operation: operation, ctx: ctx,
+                    message: `operation "${operation?.name}" requires ifMatch (the etag of the entity)`,
+                    details: { suggestion: 'Fetch the entity and send its current etag as ifMatch.' },
+                });
+            }
+            return;
+        }
+        if (ctx.ifMatch !== currentEtag) {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-CNF', status: 409, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}": etag mismatch (expected ${currentEtag}, got ${ctx.ifMatch})`,
+                details: {
+                    expected: currentEtag,
+                    received: ctx.ifMatch,
+                    suggestion: 'Fetch the entity again and retry with its fresh etag.',
+                },
+            });
+        }
+    }
+    /**
+     * Applies the patch whitelist of the operation.
+     * @param patch - the caller-provided patch object
+     * @returns the whitelisted patch and the dropped field names (unchanged patch without a whitelist)
+     * @throws 400 `DyFM-OPG-PTY` (not an object) · `DyFM-OPG-PFD` (rejected fields) · `DyFM-OPG-PEM` (nothing left)
+     */
+    static filterPatch(operation, patch, ctx) {
+        if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-PTY', status: 400, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}": patch must be an object`,
+            });
+        }
+        const declared = DyFM_OperationGuardrails_Util.patchFieldsOf(operation?.guardrails?.patchWhitelist);
+        // no whitelist declared: the guardrail is not active for this operation
+        if (!declared) {
+            return { patch: { ...patch }, droppedFields: [] };
+        }
+        const allowedFields = declared.map((one) => one.field);
+        const filtered = {};
+        const droppedFields = [];
+        Object.keys(patch).forEach((field) => {
+            if (allowedFields.includes(field)) {
+                filtered[field] = patch[field];
+            }
+            else {
+                droppedFields.push(field);
+            }
+        });
+        if (droppedFields.length && operation.guardrails?.unknownPatchFields === 'reject') {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-PFD', status: 400, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}": patch fields not allowed: ${droppedFields.join(', ')}`,
+                details: { droppedFields: droppedFields, allowedFields: allowedFields },
+            });
+        }
+        if (!Object.keys(filtered).length) {
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-PEM', status: 400, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}": the patch has no allowed field`,
+                details: { droppedFields: droppedFields, allowedFields: allowedFields },
+            });
+        }
+        // value check AFTER filtering: a dropped field is not the caller's problem to fix, a wrong value is
+        const violations = DyFM_OperationGuardrails_Util.checkPatchValues(declared, filtered);
+        if (violations.length) {
+            const first = violations[0];
+            throw DyFM_OperationGuardrails_Util.error({
+                errorCode: 'DyFM-OPG-PVL', status: 400, operation: operation, ctx: ctx,
+                message: `operation "${operation?.name}": patch field "${first.field}" expects a ${first.expectedType} value`,
+                details: { ...first, violations: violations },
+            });
+        }
+        return { patch: filtered, droppedFields: droppedFields };
+    }
+    /**
+     * Checks the values of an ALREADY FILTERED patch against the declared field types — and only reports;
+     * it never throws.
+     *
+     * # Why this is public and error-free
+     *
+     * The RULE (what a usable value is) belongs to the bedrock, but the ERROR SHAPE belongs to the transport:
+     * an operation raises a coded `DyFM_Error`, while a hand-written MCP or REST handler has its own error
+     * contract that its callers already depend on. A shared throwing helper would force one of them to adopt
+     * the other's error — a consumer-visible change for no benefit.
+     *
+     * ⚠️ MEASURED NEED (HP-DOPL 8.2, 2026-09-19): the organizer's LIVE MCP route has its own patch validator
+     * and its own error type; it needs exactly this rule and none of this package's error handling. Without
+     * this method it would have to copy the type checks — a second owner of the same logic.
+     *
+     * @param fields - the declared patch fields (use `patchFieldsOf` to normalize a raw whitelist)
+     * @param patch - the patch to check; fields not present in it are skipped
+     * @returns one entry per violating field (empty when every value is usable)
+     */
+    static checkPatchValues(fields, patch) {
+        const violations = [];
+        fields.forEach((one) => {
+            if (!one.type || !(one.field in patch))
+                return;
+            const value = patch[one.field];
+            if (value === null && one.nullable)
+                return;
+            if (!DyFM_OperationGuardrails_Util.isPatchValueValid(value, one.type)) {
+                violations.push({
+                    field: one.field,
+                    expectedType: one.type,
+                    nullable: Boolean(one.nullable),
+                    receivedType: value === null ? 'null' : typeof value,
+                });
+            }
+        });
+        return violations;
+    }
+    /**
+     * Normalizes a `patchWhitelist` into typed entries, so the rest of the code has ONE shape to handle.
+     * @param whitelist - the declared whitelist (names, typed entries, or a mix of both)
+     * @returns the normalized entries, or `undefined` when no whitelist is declared
+     */
+    static patchFieldsOf(whitelist) {
+        if (!whitelist)
+            return undefined;
+        return whitelist.map((one) => typeof one === 'string' ? { field: one } : one);
+    }
+    /**
+     * Checks a patch value against its declared type.
+     * @param value - the value the caller sent
+     * @param type - the declared type of the field
+     * @returns whether the value is usable for that type
+     */
+    static isPatchValueValid(value, type) {
+        switch (type) {
+            case DyFM_OperationPatchField_Type.string:
+                return typeof value === 'string';
+            case DyFM_OperationPatchField_Type.number:
+                return typeof value === 'number' && Number.isFinite(value);
+            case DyFM_OperationPatchField_Type.boolean:
+                return typeof value === 'boolean';
+            case DyFM_OperationPatchField_Type.date:
+                // deliberately the SAME check a create path performs: the value must yield a valid date
+                return ((typeof value === 'string' && Boolean(value.trim())) ||
+                    (typeof value === 'number' && Number.isFinite(value)) ||
+                    value instanceof Date) && !isNaN(new Date(value).getTime());
+            case DyFM_OperationPatchField_Type.object:
+                return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+            case DyFM_OperationPatchField_Type.array:
+                return Array.isArray(value);
+            default:
+                return true;
+        }
+    }
+    /** Builds a coded guardrail error carrying the operation, the requestId and the details. */
+    static error(set) {
+        return new DyFM_Error({
+            errorCode: set.errorCode,
+            status: set.status,
+            message: set.message,
+            additionalContent: { operation: set.operation?.name, requestId: set.ctx?.requestId, ...set.details },
+        });
+    }
+}

package/build-esm/_collections/utils/operation-run.util.js

@@ -0,0 +1,81 @@
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import { DyFM_OperationIfMatch_Type } from '../../_enums/operation-if-match.type-enum';
+import { DyFM_OperationAuthz_Util } from './operation-authz.util';
+import { DyFM_OperationGuardrails_Util } from './operation-guardrails.util';
+/**
+ * The single execution path of an operation (HP-DOPL MP-1.2, decision D-2): every transport adapter
+ * calls `execute`, so authorization and error shaping can not diverge between REST, MCP and CLI.
+ *
+ * @example
+ * ```ts
+ * const outcome: DyFM_OperationRun_Result<Task> = await DyFM_OperationRun_Util.execute(getTask, ctx, [ taskId ]);
+ * ```
+ */
+export class DyFM_OperationRun_Util {
+    /**
+     * Authorizes and runs the operation.
+     * @param operation - the operation to run; must have a `run` implementation
+     * @param ctx - the call context built by the transport adapter
+     * @param inputs - the positional inputs of `run`, after the context
+     * @returns the result and the non-fatal warnings; throws a coded `DyFM_Error` on any failure
+     */
+    static async execute(operation, ctx, inputs) {
+        // a definition without implementation (e.g. a client-side copy) can not be executed
+        if (typeof operation?.run !== 'function') {
+            throw new DyFM_Error({
+                errorCode: 'DyFM-OPR-NRN',
+                status: 501,
+                message: `Operation "${operation?.name}" has no run implementation`,
+                additionalContent: { operation: operation?.name, requestId: ctx?.requestId },
+            });
+        }
+        // authorization happens before any work, on every transport alike
+        const authz = DyFM_OperationAuthz_Util.assert(operation, ctx);
+        // guardrail preconditions after authorization, so an unauthorized caller learns nothing about them
+        DyFM_OperationGuardrails_Util.assertPreconditions(operation, ctx);
+        try {
+            const result = await operation.run(ctx, ...(inputs ?? []));
+            return { result: result, warnings: DyFM_OperationRun_Util.warningsOf(operation, ctx, authz) };
+        }
+        catch (error) {
+            // a coded DyFM_Error is kept as-is, anything else is wrapped with the operation context
+            if (error instanceof DyFM_Error) {
+                throw error;
+            }
+            throw new DyFM_Error({
+                errorCode: 'DyFM-OPR-RUN',
+                message: `Operation "${operation.name}" failed`,
+                error: error,
+                additionalContent: { operation: operation.name, requestId: ctx?.requestId },
+            });
+        }
+    }
+    /**
+     * Collects the non-fatal warnings of a successful call.
+     * `if-match-ignored`: the caller sent `ifMatch`, but the operation does not check it — the caller must not
+     * believe the write was protected against concurrent changes.
+     */
+    static warningsOf(operation, ctx, authz) {
+        const warnings = authz.warning ? [authz.warning] : [];
+        const ifMatchMode = operation.guardrails?.ifMatch ?? DyFM_OperationIfMatch_Type.none;
+        if (ctx?.ifMatch && ifMatchMode === DyFM_OperationIfMatch_Type.none) {
+            warnings.push('if-match-ignored');
+        }
+        return warnings;
+    }
+    /**
+     * Transitional bridge (D-2): wraps an existing route `simpleTask` as a `run` implementation.
+     * The context is ignored, because a `simpleTask` never received one; the wrapped operation still
+     * gets the shared authorization of `execute`.
+     * @param simpleTask - the existing route task
+     */
+    static fromSimpleTask(simpleTask) {
+        if (typeof simpleTask !== 'function') {
+            throw new DyFM_Error({
+                errorCode: 'DyFM-OPR-BRG',
+                message: 'fromSimpleTask requires a simpleTask function',
+            });
+        }
+        return (ctx, ...inputs) => simpleTask(...inputs);
+    }
+}

package/build-esm/_collections/utils/operation-schema.util.js

@@ -0,0 +1,159 @@
+import { DyFM_BasicProperty_Type } from '../../_enums/basic-property-type.enum';
+import { DyFM_OperationIfMatch_Type } from '../../_enums/operation-if-match.type-enum';
+import { DyFM_getBasicPropertyType } from './utilities.util';
+/**
+ * Generates the input JSON-schema of an operation (HP-DOPL MP-1.6, DMCP-005) from the runtime data model
+ * description (`bodyParams.properties`) — TypeScript generics do not exist at runtime, the properties do.
+ * Explicit `inputs` are added on top and override a body property of the same name.
+ * The guardrail arguments the operation honours are advertised too (`ifMatch` unless `guardrails.ifMatch` is `none`,
+ * required when it is `required`; `dryRun` when `guardrails.dryRun`), so a client that validates against the closed
+ * schema can still send them — a declared input of the same name is never overridden.
+ *
+ * Left out on purpose:
+ * - server-managed metadata (every key starting with `_`, e.g. `_id`, `__v`, `__created`);
+ * - `forbidden`, `readonly` and function-typed properties;
+ * - the `authz.ownership` field — ownership is resolved server-side, never taken from caller input.
+ *
+ * @example
+ * ```ts
+ * const schema: DyFM_Operation_JsonSchema = DyFM_OperationSchema_Util.inputSchema(createTask);
+ * // { type: 'object', properties: { title: { type: 'string' } }, required: [ 'title' ], additionalProperties: false }
+ * ```
+ */
+export class DyFM_OperationSchema_Util {
+    /**
+     * Builds the object schema of all inputs of the operation.
+     * @param operation - the operation description
+     */
+    static inputSchema(operation) {
+        // body properties first, so explicit inputs can override them
+        const body = DyFM_OperationSchema_Util.objectSchema(operation?.bodyParams?.properties, operation?.authz?.ownership);
+        const properties = body.properties ?? {};
+        const required = new Set(body.required ?? []);
+        Object.entries(operation?.inputs ?? {}).forEach(([key, input]) => {
+            properties[key] = DyFM_OperationSchema_Util.inputSettingsSchema(input);
+            // the explicit input decides alone whether the name is required
+            if (input.required === true) {
+                required.add(key);
+            }
+            else {
+                required.delete(key);
+            }
+        });
+        DyFM_OperationSchema_Util.addGuardrailArgs(operation, properties, required);
+        const schema = {
+            type: 'object',
+            properties: properties,
+            additionalProperties: false,
+        };
+        if (required.size) {
+            schema.required = [...required];
+        }
+        return schema;
+    }
+    /**
+     * Adds the guardrail arguments the operation honours (never over a declared input of the same name).
+     * @param operation - the operation description
+     * @param properties - the schema properties to extend
+     * @param required - the required names to extend
+     */
+    static addGuardrailArgs(operation, properties, required) {
+        const ifMatch = operation?.guardrails?.ifMatch ?? DyFM_OperationIfMatch_Type.none;
+        if (ifMatch !== DyFM_OperationIfMatch_Type.none && !properties.ifMatch) {
+            properties.ifMatch = {
+                type: 'string',
+                description: 'The current etag of the entity; the write is refused when the entity changed since.',
+            };
+            if (ifMatch === DyFM_OperationIfMatch_Type.required) {
+                required.add('ifMatch');
+            }
+        }
+        if (operation?.guardrails?.dryRun === true && !properties.dryRun) {
+            properties.dryRun = { type: 'boolean', description: 'Validate and preview the change without saving it.' };
+        }
+    }
+    /**
+     * Maps one data property (recursively for objects) to a schema.
+     * @param property - the data property params
+     */
+    static propertySchema(property) {
+        const basicType = DyFM_OperationSchema_Util.basicTypeOf(property?.type);
+        const schema = DyFM_OperationSchema_Util.typeSchema(basicType);
+        // the declared type text (e.g. `string[]`) is kept in nonBasicType once the params are constructed
+        const declaredType = String(property?.nonBasicType ?? property?.type ?? '');
+        // array element type
+        if (basicType === DyFM_BasicProperty_Type.array && declaredType.endsWith('[]')) {
+            schema.items = DyFM_OperationSchema_Util.typeSchema(DyFM_OperationSchema_Util.basicTypeOf(declaredType.slice(0, -2)));
+        }
+        // nested object properties
+        if (basicType === DyFM_BasicProperty_Type.object && property.subObjectParams) {
+            Object.assign(schema, DyFM_OperationSchema_Util.objectSchema(property.subObjectParams));
+        }
+        if (property?.default !== undefined) {
+            schema.default = property.default;
+        }
+        if (typeof property?.minlength === 'number') {
+            schema.minLength = property.minlength;
+        }
+        if (typeof property?.maxlength === 'number') {
+            schema.maxLength = property.maxlength;
+        }
+        return schema;
+    }
+    /**
+     * Builds an object schema from data properties, leaving out the fields a caller must not set.
+     * @param dataProperties - the data model properties
+     * @param excludedKey - an additional field to leave out (the ownership field)
+     */
+    static objectSchema(dataProperties, excludedKey) {
+        const properties = {};
+        const required = [];
+        Object.entries(dataProperties ?? {}).forEach(([key, property]) => {
+            if (key === excludedKey || !DyFM_OperationSchema_Util.isCallerSettable(key, property)) {
+                return;
+            }
+            properties[key] = DyFM_OperationSchema_Util.propertySchema(property);
+            // a default makes the field optional for the caller
+            if (property.required === true && property.default === undefined) {
+                required.push(key);
+            }
+        });
+        const schema = { type: 'object', properties: properties, additionalProperties: false };
+        if (required.length) {
+            schema.required = required;
+        }
+        return schema;
+    }
+    /** Maps an explicit operation input to a schema. */
+    static inputSettingsSchema(input) {
+        const schema = DyFM_OperationSchema_Util.typeSchema(input.type);
+        if (input.description) {
+            schema.description = input.description;
+        }
+        if (input.enum) {
+            schema.enum = [...input.enum];
+        }
+        if (input.default !== undefined) {
+            schema.default = input.default;
+        }
+        return schema;
+    }
+    /** Base schema of a basic type; dates travel as ISO strings. */
+    static typeSchema(type) {
+        if (type === DyFM_BasicProperty_Type.date) {
+            return { type: 'string', format: 'date-time' };
+        }
+        return { type: type };
+    }
+    /** A property is caller-settable unless it is metadata, forbidden, readonly or a function. */
+    static isCallerSettable(key, property) {
+        return !key.startsWith('_') &&
+            property?.forbidden !== true &&
+            property?.readonly !== true &&
+            DyFM_OperationSchema_Util.basicTypeOf(property?.type) !== DyFM_BasicProperty_Type.function;
+    }
+    /** Normalizes a declared type text to a basic type; a missing type counts as `object`. */
+    static basicTypeOf(type) {
+        return type ? DyFM_getBasicPropertyType(type) : DyFM_BasicProperty_Type.object;
+    }
+}

package/build-esm/_collections/utils/regex/password-regex.util.js

@@ -0,0 +1,56 @@
+export const DyFM_passwordRegex = new RegExp('^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.*[!@#$%^&*]){6,}');
+/* export const DyFM_ALLPasswordRegexUserMessages: string =
+  'Password must include at least one lowercase letter. ' +
+  'Password must include at least one uppercase letter.' +
+  'Password must include at least one digit.' +
+  'Password must include at least one of the !@#$%^&* characters.' +
+  'Password must be at least 6 characters long.'; */
+/**
+  * returns an array of errors for a given password if it not match all the requirements
+  *
+  * @example
+  * ```ts
+  * const errors = DyFM_getPasswordErrors('Invalid1');
+  * console.log(errors); // ['Password must include at least one of the !@#$%^&* characters.']
+  *
+  * const errors = DyFM_getPasswordErrors('ValidPassword1!');
+  * console.log(errors); // []
+  * ```
+  */
+export function DyFM_getPasswordErrors(password) {
+    const errors = [];
+    DyFM_passwordErrorsOneByOne.forEach((error) => {
+        if (!error.regex.test(password)) {
+            errors.push(error.message);
+        }
+    });
+    return errors;
+}
+const DyFM_passwordErrorsOneByOne = [
+    {
+        regex: new RegExp('^(?=.*[a-z])'),
+        code: 'pwErrorLowercase',
+        message: 'Password must include at least one lowercase letter.'
+    },
+    {
+        regex: new RegExp('^(?=.*[A-Z])'),
+        code: 'pwErrorUppercase',
+        message: 'Password must include at least one uppercase letter.'
+    },
+    {
+        regex: new RegExp('^(?=.*[0-9])'),
+        code: 'pwErrorDigit',
+        message: 'Password must include at least one digit.'
+    },
+    {
+        regex: new RegExp('^(?=.*[!@#$%^&*])'),
+        code: 'pwErrorSpecialChar',
+        message: 'Password must include at least one of the !@#$%^&* characters.'
+    },
+    {
+        regex: new RegExp('^(?=.{6,})'),
+        code: 'pwErrorLength',
+        message: 'Password must be at least 6 characters long.'
+    },
+];
+//'!@#$%^&*+-_<>?.,;:|~'

package/build-esm/_collections/utils/regex/regex.util.js

@@ -0,0 +1 @@
+export const DyFM_emailRegex = new RegExp('^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$');