@nhtio/validation 1.20251028.0 → 1.20251029.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "1.20251028.0",
+  "version": "1.20251029.1",
   "description": "A powerful schema description language and data validator",
   "keywords": [],
   "author": "Jak Giveon <jak@nht.io>",
@@ -21,7 +21,8 @@
     },
     "onlyBuiltDependencies": [
       "es5-ext",
-      "esbuild"
+      "esbuild",
+      "sqlite3"
     ]
   },
   "packageManager": "pnpm@10.8.0+sha512.0e82714d1b5b43c74610193cb20734897c1d00de89d0e18420aebc5977fa13d780a9cb05734624e81ebd81cc876cd464794850641c48b9544326b5622ca29971",

package/private/patches/knex.d.ts

@@ -1,4 +1,6 @@
+import type { Knex } from 'knex';
 import type { SchemaTypeDefinititionMiddlewareFn } from '../core/root';
+import type { KnexSchemaConnection } from '../schemas';
 export declare const knexMessages: {
     'knex.unique': string;
     'knex.exists': string;
@@ -7,4 +9,8 @@ export declare const knexMessages: {
     'knex.invalidColumn': string;
     'knex.internal': string;
 };
+export declare const resolveQueryBuilder: (connection: KnexSchemaConnection, table: string) => {
+    client: Knex;
+    query: Knex.QueryBuilder;
+};
 export declare const knex: SchemaTypeDefinititionMiddlewareFn;

package/private/utils.d.ts

@@ -1,4 +1,71 @@
 import type { Schema } from './schemas';
+/**
+ * Options for encoding and decoding validation schemas.
+ *
+ * These options control what gets serialized when encoding schemas and how
+ * they're reconstructed during decoding. The defaults prioritize security
+ * and are designed for the most common use case: sharing validation rules
+ * between frontend and backend environments.
+ */
+export type EncoderOptions = {
+    /**
+     * Include database connections and database validation rules in the encoded schema.
+     *
+     * When `false` (default):
+     * - Database connections (`.knex()`, `.db()`) are stripped from the encoded schema
+     * - Database validation rules (`.uniqueInDb()`, `.existsInDb()`) are converted to no-ops
+     * - Filter functions in database rules are replaced with empty functions
+     * - This prevents credential leakage and reduces payload size
+     *
+     * When `true`:
+     * - Database connection configurations are serialized (if they're plain objects)
+     * - Database validation rules and their filter functions are preserved
+     * - **Security warning**: Only use this in trusted backend-to-backend communication
+     * - Encoded schemas will require re-attaching database connections after decoding
+     *
+     * **Why this defaults to `false`:**
+     * 1. **Security**: Prevents accidental exposure of database credentials in client-side code
+     * 2. **Use case alignment**: Frontend validation typically doesn't need database rules
+     * 3. **Credential safety**: Database connections often contain sensitive connection strings
+     * 4. **Function security**: Custom filter functions may contain business logic or credentials
+     *
+     * @default false
+     *
+     * @example Frontend/Backend Schema Sharing (default)
+     * ```typescript
+     * // Backend
+     * const schema = joi.object({
+     *   email: joi.string().email().uniqueInDb('users', 'email')
+     * }).knex(db)
+     *
+     * const encoded = encode(schema) // withDatabase defaults to false
+     * // Database rules are stripped, safe to send to frontend
+     *
+     * // Frontend receives and decodes
+     * const frontendSchema = decode(encoded)
+     * // Only gets email format validation, no database checks
+     * ```
+     *
+     * @example Backend-to-Backend Schema Transfer
+     * ```typescript
+     * // Service A
+     * const schema = joi.object({
+     *   username: joi.string().uniqueInDb('users', 'username', {
+     *     filter: async (query) => query.where('tenant_id', tenantId)
+     *   })
+     * }).knex({ client: 'pg', connection: { host: 'localhost', ... } })
+     *
+     * const encoded = encode(schema, { withDatabase: true })
+     * // Sends to trusted Service B
+     *
+     * // Service B
+     * const decoded = decode(encoded, { withDatabase: true })
+     * const rehydrated = decoded.knex(serviceB_db_connection)
+     * // Now has full database validation capabilities
+     * ```
+     */
+    withDatabase?: boolean;
+};
 /**
  * Encodes a validation schema into a compressed, base64-encoded string for transport between environments.
  *
@@ -46,7 +113,7 @@ import type { Schema } from './schemas';
  *
  * @see {@link decode} For decoding schemas from encoded strings
  */
-export declare const encode: (schema: Schema) => string;
+export declare const encode: (schema: Schema, options?: EncoderOptions) => string;
 /**
  * Decodes a base64-encoded schema string back into a usable validation schema.
  *
@@ -63,6 +130,7 @@ export declare const encode: (schema: Schema) => string;
  * - Schema reconstruction using Joi's build method
  *
  * @param base64 - The base64-encoded schema string
+ * @param options - Decoding options
  * @returns A reconstructed validation schema ready for validation
  * @throws {TypeError} When the encoded string is not a valid schema
  * @throws {TypeError} When the schema version is invalid or incompatible
@@ -101,6 +169,18 @@ export declare const encode: (schema: Schema) => string;
  * const schema = decode(oldSchema) // Works - backward compatible
  * ```
  *
+ * @security
+ * **IMPORTANT: Only decode schemas from trusted sources.**
+ *
+ * Decoded schemas may contain serialized functions that are evaluated using the
+ * Function constructor. Never decode schemas from:
+ * - User input or user-controlled data
+ * - Untrusted third-party APIs
+ * - Any source you do not control
+ *
+ * If the schema source is not under your direct control, validate its integrity
+ * using cryptographic signatures or checksums before decoding.
+ *
  * @see {@link encode} For encoding schemas into transportable strings
  */
-export declare const decode: (base64: string) => Schema;
+export declare const decode: (base64: string, options?: EncoderOptions) => Schema;