@rvoh/psychic 3.9.0 → 3.10.0

package/dist/cjs/src/psychic-app/index.js

@@ -44,7 +44,9 @@ export default class PsychicApp {
             if (!psychicApp.routesCb)
                 throw new PsychicAppInitMissingRoutesCallback();
             if (psychicApp.encryption?.cookies?.current)
-                this.checkEncryptionKey('cookies', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
+                this.checkEncryptionKey('cookies', 'current', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
+            if (psychicApp.encryption?.cookies?.legacy)
+                this.checkEncryptionKey('cookies', 'legacy', psychicApp.encryption.cookies.legacy.key, psychicApp.encryption.cookies.legacy.algorithm);
             await psychicApp.inflections?.();
             dreamApp.on('repl:start', context => {
                 const psychicApp = PsychicApp.getOrFail();
@@ -187,14 +189,15 @@ export default class PsychicApp {
      * are not broken by a hard failure.
      *
      * @param encryptionIdentifier - currently must be 'cookies', though this may change in the future
+     * @param keyType - whether this is the 'current' or 'legacy' key (named in the error so a misconfigured legacy key is not mistaken for the current one)
      * @param key - the encryption key you want to check
      * @param algorithm - the encryption algorithm you want to check
      */
-    static checkEncryptionKey(encryptionIdentifier, key, algorithm) {
+    static checkEncryptionKey(encryptionIdentifier, keyType, key, algorithm) {
         if (Encrypt.validateKey(key, algorithm))
             return;
         const message = `
-Your current key value for ${encryptionIdentifier} encryption is invalid.
+Your ${keyType} key value for ${encryptionIdentifier} encryption is invalid.
 Try setting it to something valid, like:
   ${Encrypt.generateKey(algorithm)}
 

package/dist/cjs/src/server/params.js

@@ -59,8 +59,11 @@ export default class Params {
                 else if (columnMetadata?.enumValues) {
                     const paramValue = params[columnName];
                     if (columnMetadata.isArray) {
+                        // Single-value query arrays are conformed to arrays upstream in
+                        // conformQueryArrayParamsToOpenapiShape, so a non-array reaching
+                        // here is a real error rather than something to coerce.
                         if (!Array.isArray(paramValue))
-                            returnObj[columnName] = ['expected an array of enum values'];
+                            throw new ParamValidationError(columnName.toString(), ['expected an array of enum values']);
                         returnObj[columnName] = paramValue.map(p => {
                             return new this(params).cast(columnName.toString(), p, 'string', {
                                 allowNull: columnMetadata.allowNull,
@@ -177,10 +180,16 @@ export default class Params {
             return paramValue;
         }
         const integerRegexp = /^-?\d+$/;
+        // Plain decimal numeric string: optional sign, digits with an optional
+        // fractional part (or a bare fractional part), and an optional decimal
+        // exponent. Deliberately excludes hex/octal/binary literals and the
+        // "Infinity"/"NaN" keywords that `Number()` would otherwise accept.
+        const decimalNumberRegexp = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
         switch (expectedType) {
             case 'string':
                 if (typeof paramValue !== 'string')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                this.throwUnlessWithinLength(paramName, paramValue, opts);
                 if (opts?.enum && !opts.enum.includes(paramValue))
                     throw new ParamValidationError(paramName, ['did not match expected enum values']);
                 if (opts?.match)
@@ -191,6 +200,7 @@ export default class Params {
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 if (!integerRegexp.test(paramValue?.toString()))
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                this.throwUnlessWithinRange(paramName, BigInt(paramValue.toString()), opts);
                 return paramValue.toString();
             case 'boolean':
                 if ([true, 'true', 1, '1'].includes(paramValue))
@@ -254,25 +264,47 @@ export default class Params {
                 }
                 throw new ParamValidationError(paramName, [typeToError(expectedType)]);
             }
-            case 'integer':
+            case 'integer': {
                 if (typeof paramValue !== 'string' && typeof paramValue !== 'number')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 if (!integerRegexp.test(paramValue?.toString()))
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
-                return parseInt(paramValue, 10);
+                const integerValue = parseInt(paramValue, 10);
+                // Reject values outside the safe-integer range: a long digit string
+                // (e.g. a 40-digit number) would otherwise be silently rounded to a
+                // nearby float by parseInt. Genuinely large integers should be cast as
+                // `bigint`, which preserves the exact value as a string.
+                if (!Number.isSafeInteger(integerValue))
+                    throw new ParamValidationError(paramName, [
+                        'expected an integer within the safe integer range (use bigint for larger values)',
+                    ]);
+                this.throwUnlessWithinRange(paramName, integerValue, opts);
+                return integerValue;
+            }
             case 'json':
                 if (typeof paramValue !== 'object')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 return paramValue;
-            case 'number':
-                if (typeof paramValue === 'number')
+            case 'number': {
+                if (typeof paramValue === 'number') {
+                    if (!Number.isFinite(paramValue))
+                        throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                    this.throwUnlessWithinRange(paramName, paramValue, opts);
                     return paramValue;
+                }
                 if (typeof paramValue === 'string') {
-                    if (paramValue.length === 0 || Number.isNaN(Number(paramValue)))
+                    // Require a plain decimal numeric string and a finite result. This
+                    // rejects hex/octal/binary forms ("0x10"), the literals "Infinity"/
+                    // "NaN", and magnitudes that overflow to Infinity ("1e999"), all of
+                    // which `Number()` would otherwise silently coerce.
+                    const numberValue = Number(paramValue);
+                    if (!decimalNumberRegexp.test(paramValue) || !Number.isFinite(numberValue))
                         throw new ParamValidationError(paramName, [typeToError(expectedType)]);
-                    return Number(paramValue);
+                    this.throwUnlessWithinRange(paramName, numberValue, opts);
+                    return numberValue;
                 }
                 throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+            }
             case 'null':
                 if (paramValue !== null)
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
@@ -352,6 +384,45 @@ export default class Params {
             return paramValue;
         throw new ParamValidationError(paramName, [typeToError(expectedType)]);
     }
+    /**
+     * Enforces `minLength`/`maxLength` (inclusive) against an already-coerced
+     * string value, throwing {@link ParamValidationError} on violation. Mirrors
+     * JSON-schema / OpenAPI string-length constraints.
+     */
+    throwUnlessWithinLength(paramName, paramValue, opts) {
+        if (opts?.minLength !== undefined && paramValue.length < opts.minLength)
+            throw new ParamValidationError(paramName, [
+                `expected string with length no less than ${opts.minLength}`,
+            ]);
+        if (opts?.maxLength !== undefined && paramValue.length > opts.maxLength)
+            throw new ParamValidationError(paramName, [
+                `expected string with length no greater than ${opts.maxLength}`,
+            ]);
+    }
+    /**
+     * Enforces `minimum`/`maximum` (inclusive) against an already-coerced numeric
+     * value, throwing {@link ParamValidationError} on violation. Accepts a
+     * `bigint` so `bigint` casts are checked without precision loss; the bounds
+     * themselves are compared as `bigint` when they are integers and otherwise
+     * fall back to floating-point comparison. Mirrors JSON-schema / OpenAPI
+     * numeric-range constraints.
+     */
+    throwUnlessWithinRange(paramName, paramValue, opts) {
+        if (opts?.minimum !== undefined && this.isBelowNumericBound(paramValue, opts.minimum))
+            throw new ParamValidationError(paramName, [`expected a value no less than ${opts.minimum}`]);
+        if (opts?.maximum !== undefined && this.isAboveNumericBound(paramValue, opts.maximum))
+            throw new ParamValidationError(paramName, [`expected a value no greater than ${opts.maximum}`]);
+    }
+    isBelowNumericBound(value, bound) {
+        if (typeof value === 'bigint')
+            return Number.isInteger(bound) ? value < BigInt(bound) : Number(value) < bound;
+        return value < bound;
+    }
+    isAboveNumericBound(value, bound) {
+        if (typeof value === 'bigint')
+            return Number.isInteger(bound) ? value > BigInt(bound) : Number(value) > bound;
+        return value > bound;
+    }
     throwUnlessAllowNull(paramName, paramValue, message, { allowNull = false } = {}) {
         const isNullOrUndefined = [null, undefined].includes(paramValue);
         if (allowNull && isNullOrUndefined)

package/dist/esm/src/psychic-app/index.js

@@ -44,7 +44,9 @@ export default class PsychicApp {
             if (!psychicApp.routesCb)
                 throw new PsychicAppInitMissingRoutesCallback();
             if (psychicApp.encryption?.cookies?.current)
-                this.checkEncryptionKey('cookies', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
+                this.checkEncryptionKey('cookies', 'current', psychicApp.encryption.cookies.current.key, psychicApp.encryption.cookies.current.algorithm);
+            if (psychicApp.encryption?.cookies?.legacy)
+                this.checkEncryptionKey('cookies', 'legacy', psychicApp.encryption.cookies.legacy.key, psychicApp.encryption.cookies.legacy.algorithm);
             await psychicApp.inflections?.();
             dreamApp.on('repl:start', context => {
                 const psychicApp = PsychicApp.getOrFail();
@@ -187,14 +189,15 @@ export default class PsychicApp {
      * are not broken by a hard failure.
      *
      * @param encryptionIdentifier - currently must be 'cookies', though this may change in the future
+     * @param keyType - whether this is the 'current' or 'legacy' key (named in the error so a misconfigured legacy key is not mistaken for the current one)
      * @param key - the encryption key you want to check
      * @param algorithm - the encryption algorithm you want to check
      */
-    static checkEncryptionKey(encryptionIdentifier, key, algorithm) {
+    static checkEncryptionKey(encryptionIdentifier, keyType, key, algorithm) {
         if (Encrypt.validateKey(key, algorithm))
             return;
         const message = `
-Your current key value for ${encryptionIdentifier} encryption is invalid.
+Your ${keyType} key value for ${encryptionIdentifier} encryption is invalid.
 Try setting it to something valid, like:
   ${Encrypt.generateKey(algorithm)}
 

package/dist/esm/src/server/params.js

@@ -59,8 +59,11 @@ export default class Params {
                 else if (columnMetadata?.enumValues) {
                     const paramValue = params[columnName];
                     if (columnMetadata.isArray) {
+                        // Single-value query arrays are conformed to arrays upstream in
+                        // conformQueryArrayParamsToOpenapiShape, so a non-array reaching
+                        // here is a real error rather than something to coerce.
                         if (!Array.isArray(paramValue))
-                            returnObj[columnName] = ['expected an array of enum values'];
+                            throw new ParamValidationError(columnName.toString(), ['expected an array of enum values']);
                         returnObj[columnName] = paramValue.map(p => {
                             return new this(params).cast(columnName.toString(), p, 'string', {
                                 allowNull: columnMetadata.allowNull,
@@ -177,10 +180,16 @@ export default class Params {
             return paramValue;
         }
         const integerRegexp = /^-?\d+$/;
+        // Plain decimal numeric string: optional sign, digits with an optional
+        // fractional part (or a bare fractional part), and an optional decimal
+        // exponent. Deliberately excludes hex/octal/binary literals and the
+        // "Infinity"/"NaN" keywords that `Number()` would otherwise accept.
+        const decimalNumberRegexp = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
         switch (expectedType) {
             case 'string':
                 if (typeof paramValue !== 'string')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                this.throwUnlessWithinLength(paramName, paramValue, opts);
                 if (opts?.enum && !opts.enum.includes(paramValue))
                     throw new ParamValidationError(paramName, ['did not match expected enum values']);
                 if (opts?.match)
@@ -191,6 +200,7 @@ export default class Params {
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 if (!integerRegexp.test(paramValue?.toString()))
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                this.throwUnlessWithinRange(paramName, BigInt(paramValue.toString()), opts);
                 return paramValue.toString();
             case 'boolean':
                 if ([true, 'true', 1, '1'].includes(paramValue))
@@ -254,25 +264,47 @@ export default class Params {
                 }
                 throw new ParamValidationError(paramName, [typeToError(expectedType)]);
             }
-            case 'integer':
+            case 'integer': {
                 if (typeof paramValue !== 'string' && typeof paramValue !== 'number')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 if (!integerRegexp.test(paramValue?.toString()))
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
-                return parseInt(paramValue, 10);
+                const integerValue = parseInt(paramValue, 10);
+                // Reject values outside the safe-integer range: a long digit string
+                // (e.g. a 40-digit number) would otherwise be silently rounded to a
+                // nearby float by parseInt. Genuinely large integers should be cast as
+                // `bigint`, which preserves the exact value as a string.
+                if (!Number.isSafeInteger(integerValue))
+                    throw new ParamValidationError(paramName, [
+                        'expected an integer within the safe integer range (use bigint for larger values)',
+                    ]);
+                this.throwUnlessWithinRange(paramName, integerValue, opts);
+                return integerValue;
+            }
             case 'json':
                 if (typeof paramValue !== 'object')
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
                 return paramValue;
-            case 'number':
-                if (typeof paramValue === 'number')
+            case 'number': {
+                if (typeof paramValue === 'number') {
+                    if (!Number.isFinite(paramValue))
+                        throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+                    this.throwUnlessWithinRange(paramName, paramValue, opts);
                     return paramValue;
+                }
                 if (typeof paramValue === 'string') {
-                    if (paramValue.length === 0 || Number.isNaN(Number(paramValue)))
+                    // Require a plain decimal numeric string and a finite result. This
+                    // rejects hex/octal/binary forms ("0x10"), the literals "Infinity"/
+                    // "NaN", and magnitudes that overflow to Infinity ("1e999"), all of
+                    // which `Number()` would otherwise silently coerce.
+                    const numberValue = Number(paramValue);
+                    if (!decimalNumberRegexp.test(paramValue) || !Number.isFinite(numberValue))
                         throw new ParamValidationError(paramName, [typeToError(expectedType)]);
-                    return Number(paramValue);
+                    this.throwUnlessWithinRange(paramName, numberValue, opts);
+                    return numberValue;
                 }
                 throw new ParamValidationError(paramName, [typeToError(expectedType)]);
+            }
             case 'null':
                 if (paramValue !== null)
                     throw new ParamValidationError(paramName, [typeToError(expectedType)]);
@@ -352,6 +384,45 @@ export default class Params {
             return paramValue;
         throw new ParamValidationError(paramName, [typeToError(expectedType)]);
     }
+    /**
+     * Enforces `minLength`/`maxLength` (inclusive) against an already-coerced
+     * string value, throwing {@link ParamValidationError} on violation. Mirrors
+     * JSON-schema / OpenAPI string-length constraints.
+     */
+    throwUnlessWithinLength(paramName, paramValue, opts) {
+        if (opts?.minLength !== undefined && paramValue.length < opts.minLength)
+            throw new ParamValidationError(paramName, [
+                `expected string with length no less than ${opts.minLength}`,
+            ]);
+        if (opts?.maxLength !== undefined && paramValue.length > opts.maxLength)
+            throw new ParamValidationError(paramName, [
+                `expected string with length no greater than ${opts.maxLength}`,
+            ]);
+    }
+    /**
+     * Enforces `minimum`/`maximum` (inclusive) against an already-coerced numeric
+     * value, throwing {@link ParamValidationError} on violation. Accepts a
+     * `bigint` so `bigint` casts are checked without precision loss; the bounds
+     * themselves are compared as `bigint` when they are integers and otherwise
+     * fall back to floating-point comparison. Mirrors JSON-schema / OpenAPI
+     * numeric-range constraints.
+     */
+    throwUnlessWithinRange(paramName, paramValue, opts) {
+        if (opts?.minimum !== undefined && this.isBelowNumericBound(paramValue, opts.minimum))
+            throw new ParamValidationError(paramName, [`expected a value no less than ${opts.minimum}`]);
+        if (opts?.maximum !== undefined && this.isAboveNumericBound(paramValue, opts.maximum))
+            throw new ParamValidationError(paramName, [`expected a value no greater than ${opts.maximum}`]);
+    }
+    isBelowNumericBound(value, bound) {
+        if (typeof value === 'bigint')
+            return Number.isInteger(bound) ? value < BigInt(bound) : Number(value) < bound;
+        return value < bound;
+    }
+    isAboveNumericBound(value, bound) {
+        if (typeof value === 'bigint')
+            return Number.isInteger(bound) ? value > BigInt(bound) : Number(value) > bound;
+        return value > bound;
+    }
     throwUnlessAllowNull(paramName, paramValue, message, { allowNull = false } = {}) {
         const isNullOrUndefined = [null, undefined].includes(paramValue);
         if (allowNull && isNullOrUndefined)

package/dist/types/src/psychic-app/index.d.ts

@@ -125,6 +125,7 @@ export default class PsychicApp {
      * are not broken by a hard failure.
      *
      * @param encryptionIdentifier - currently must be 'cookies', though this may change in the future
+     * @param keyType - whether this is the 'current' or 'legacy' key (named in the error so a misconfigured legacy key is not mistaken for the current one)
      * @param key - the encryption key you want to check
      * @param algorithm - the encryption algorithm you want to check
      */

package/dist/types/src/server/params.d.ts

@@ -77,6 +77,23 @@ export default class Params {
     private validateOpenapiOrThrow;
     restrict(allowed: string[]): PsychicParamsDictionary;
     private matchRegexOrThrow;
+    /**
+     * Enforces `minLength`/`maxLength` (inclusive) against an already-coerced
+     * string value, throwing {@link ParamValidationError} on violation. Mirrors
+     * JSON-schema / OpenAPI string-length constraints.
+     */
+    private throwUnlessWithinLength;
+    /**
+     * Enforces `minimum`/`maximum` (inclusive) against an already-coerced numeric
+     * value, throwing {@link ParamValidationError} on violation. Accepts a
+     * `bigint` so `bigint` casts are checked without precision loss; the bounds
+     * themselves are compared as `bigint` when they are integers and otherwise
+     * fall back to floating-point comparison. Mirrors JSON-schema / OpenAPI
+     * numeric-range constraints.
+     */
+    private throwUnlessWithinRange;
+    private isBelowNumericBound;
+    private isAboveNumericBound;
     private throwUnlessAllowNull;
 }
 export type ValidatedReturnType<ExpectedType, OptsType> = ExpectedType extends RegExp ? string : ExpectedType extends 'string' ? OptsType extends {
@@ -113,6 +130,30 @@ export type ParamsCastOptions<EnumType> = {
     allowNull?: boolean;
     match?: RegExp;
     enum?: EnumType;
+    /**
+     * Maximum permitted string length (inclusive). Enforced after coercion for
+     * `string` casts (and element-wise for `string[]`). Mirrors JSON-schema /
+     * OpenAPI `maxLength`.
+     */
+    maxLength?: number;
+    /**
+     * Minimum permitted string length (inclusive). Enforced after coercion for
+     * `string` casts (and element-wise for `string[]`). Mirrors JSON-schema /
+     * OpenAPI `minLength`.
+     */
+    minLength?: number;
+    /**
+     * Minimum permitted numeric value (inclusive). Enforced after coercion for
+     * `number`/`integer`/`bigint` casts (and element-wise for their array
+     * variants). Mirrors JSON-schema / OpenAPI `minimum`.
+     */
+    minimum?: number;
+    /**
+     * Maximum permitted numeric value (inclusive). Enforced after coercion for
+     * `number`/`integer`/`bigint` casts (and element-wise for their array
+     * variants). Mirrors JSON-schema / OpenAPI `maximum`.
+     */
+    maximum?: number;
 };
 interface ParamsForOptsBase<OnlyArray> {
     array?: boolean;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "author": "RVOHealth",
   "publishConfig": {
     "access": "public"