@zintrust/core 0.1.15 → 0.1.17

package/src/middleware/CsrfMiddleware.js

@@ -3,9 +3,9 @@
  * Protects against Cross-Site Request Forgery attacks
  * Uses CsrfTokenManager for token generation and validation
  */
-import { generateSecureJobId } from '../common/uuid.js';
 import { Logger } from '../config/logger.js';
 import { CsrfTokenManager } from '../security/CsrfTokenManager.js';
+import { SessionManager } from '../session/SessionManager.js';
 const DEFAULT_OPTIONS = {
     cookieName: 'XSRF-TOKEN',
     headerName: 'X-CSRF-Token',
@@ -19,6 +19,7 @@ export const CsrfMiddleware = Object.freeze({
     create(options = {}) {
         const config = { ...DEFAULT_OPTIONS, ...options };
         const manager = CsrfTokenManager.create();
+        const sessions = SessionManager.create();
         // Periodic cleanup to prevent memory leaks
         // Run every hour (matching default token TTL)
         const cleanupTimer = setInterval(() => {
@@ -29,35 +30,17 @@ export const CsrfMiddleware = Object.freeze({
             cleanupTimer.unref();
         }
         return async (req, res, next) => {
-            // We need a session ID to bind the token to.
-            // Assuming a session middleware has run before this and populated req.context.sessionId
-            // or we use a cookie for the session ID.
-            // For now, we'll try to get it from a cookie or generate a temporary one if missing (stateless fallback)
-            // Note: In a real scenario, this MUST be tied to the user's authenticated session.
-            // Here we check for a specific session cookie or header.
-            const cookies = parseCookies(req.getHeader('cookie') || '');
-            let sessionId = cookies['ZIN_SESSION_ID'] || req.context['sessionId'];
-            if (!sessionId) {
-                // If no session exists, we can't effectively bind CSRF to a session.
-                // However, for the sake of the middleware functioning in a stateless way (Double Submit Cookie pattern),
-                // we can generate a pseudo-session-id if one doesn't exist, but it's less secure.
-                // Ideally, this middleware should throw if session is missing.
-                // For this implementation, we'll skip if no session is found, but log a warning.
-                // Logger.warn('CSRF Middleware: No session ID found. Skipping CSRF check.');
-                // await next();
-                // return;
-                // Better approach: Generate a session ID if missing (Double Submit Cookie foundation)
-                // IMPORTANT: use a cryptographically secure generator (Sonar S2245).
-                sessionId = await generateSecureJobId('CSRF Middleware: secure crypto API not available to generate a session id');
-                // We would need to set this session cookie, but we can't easily do that without a SessionManager.
-                // We'll assume the SessionMiddleware handles session creation.
-            }
+            const cookieHeader = req.getHeader('cookie');
+            const cookies = parseCookies(typeof cookieHeader === 'string' ? cookieHeader : '');
+            // Guarantee a session id exists and a session cookie is set if missing.
+            // This allows CSRF tokens to be bound to a stable session identifier.
+            const sessionId = await sessions.ensureSessionId(req, res);
             const method = req.getMethod();
             // 1. Token Generation (for safe methods)
             if (config.ignoreMethods?.includes(method) ?? false) {
                 const token = manager.generateToken(sessionId);
                 // Set cookie for Double Submit Cookie pattern (readable by frontend)
-                res.setHeader('Set-Cookie', `${config.cookieName}=${token}; Path=/; SameSite=Strict`);
+                appendSetCookie(res, `${config.cookieName}=${token}; Path=/; SameSite=Strict`);
                 // Also expose in locals for server-side rendering
                 res.locals['csrfToken'] = token;
                 await next();
@@ -81,6 +64,18 @@ export const CsrfMiddleware = Object.freeze({
         };
     },
 });
+function appendSetCookie(res, cookie) {
+    const existing = res.getHeader('Set-Cookie');
+    if (existing === undefined) {
+        res.setHeader('Set-Cookie', cookie);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        res.setHeader('Set-Cookie', [...existing, cookie]);
+        return;
+    }
+    res.setHeader('Set-Cookie', [existing, cookie]);
+}
 /**
  * Helper to parse cookies
  */

package/src/middleware/SessionMiddleware.d.ts

@@ -0,0 +1,8 @@
+import { Middleware } from './MiddlewareStack';
+import { type SessionManagerOptions } from '../session/SessionManager';
+export type SessionOptions = SessionManagerOptions;
+export declare const SessionMiddleware: Readonly<{
+    create(options?: SessionOptions): Middleware;
+}>;
+export default SessionMiddleware;
+//# sourceMappingURL=SessionMiddleware.d.ts.map

package/src/middleware/SessionMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/SessionMiddleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAkB,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErF,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAEnD,eAAO,MAAM,iBAAiB;qBACZ,cAAc,GAAQ,UAAU;EAehD,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/middleware/SessionMiddleware.js

@@ -0,0 +1,15 @@
+import { SessionManager } from '../session/SessionManager.js';
+export const SessionMiddleware = Object.freeze({
+    create(options = {}) {
+        const manager = SessionManager.create(options);
+        return async (req, res, next) => {
+            const sessionId = await manager.ensureSessionId(req, res);
+            // Keep both request state + context aligned.
+            req.sessionId = sessionId;
+            req.context['sessionId'] = sessionId;
+            res.locals['sessionId'] = sessionId;
+            await next();
+        };
+    },
+});
+export default SessionMiddleware;

package/src/node-singletons/crypto.d.ts

@@ -3,5 +3,5 @@
  * Safe to import in both API and CLI code
  * Exported from node:crypto built-in
  */
-export { createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, } from 'node:crypto';
+export { createCipheriv, createDecipheriv, createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, timingSafeEqual, } from 'node:crypto';
 //# sourceMappingURL=crypto.d.ts.map

package/src/node-singletons/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/node-singletons/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,SAAS,GACV,MAAM,aAAa,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../../src/node-singletons/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,SAAS,EACT,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/src/node-singletons/crypto.js

@@ -3,4 +3,4 @@
  * Safe to import in both API and CLI code
  * Exported from node:crypto built-in
  */
-export { createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, } from 'node:crypto';
+export { createCipheriv, createDecipheriv, createHash, createHmac, createSign, createVerify, generateKeyPairSync, pbkdf2Sync, randomBytes, randomInt, timingSafeEqual, } from 'node:crypto';

package/src/orm/Model.d.ts

@@ -10,6 +10,20 @@ export interface ModelConfig {
     hidden: string[];
     timestamps: boolean;
     casts: Record<string, string>;
+    softDeletes?: boolean;
+    accessors?: Record<string, (value: unknown, attrs: Record<string, unknown>) => unknown>;
+    mutators?: Record<string, (value: unknown, attrs: Record<string, unknown>) => unknown>;
+    scopes?: Record<string, (builder: IQueryBuilder, ...args: unknown[]) => IQueryBuilder>;
+    observers?: Array<{
+        saving?: (model: IModel) => void | Promise<void>;
+        saved?: (model: IModel) => void | Promise<void>;
+        creating?: (model: IModel) => void | Promise<void>;
+        created?: (model: IModel) => void | Promise<void>;
+        updating?: (model: IModel) => void | Promise<void>;
+        updated?: (model: IModel) => void | Promise<void>;
+        deleting?: (model: IModel) => void | Promise<void>;
+        deleted?: (model: IModel) => void | Promise<void>;
+    }>;
     connection?: string;
 }
 export interface ModelStatic {
@@ -60,6 +74,7 @@ export type DefinedModel<T extends BoundModelMethods> = {
     find: (id: unknown) => Promise<(IModel & T) | null>;
     all: () => Promise<Array<IModel & T>>;
     query: () => IQueryBuilder;
+    scope: (name: string, ...args: unknown[]) => IQueryBuilder;
     getTable: () => string;
     db: (connection: string) => DefinedModel<T>;
 };

package/src/orm/Model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../../../src/orm/Model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Model.d.ts","sourceRoot":"","sources":["../../../src/orm/Model.ts"],"names":[],"mappings":"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"}

package/src/orm/Model.js

@@ -43,7 +43,27 @@ const castAttribute = (config, key, value) => {
 const fillAttributes = (config, attrs, newAttrs) => {
     for (const [key, value] of Object.entries(newAttrs)) {
         if (config.fillable.length === 0 || config.fillable.includes(key)) {
-            attrs[key] = castAttribute(config, key, value);
+            const mutator = config.mutators?.[key];
+            const nextValue = mutator ? mutator(value, attrs) : value;
+            attrs[key] = castAttribute(config, key, nextValue);
+        }
+    }
+};
+const applyAccessor = (config, key, attrs) => {
+    const raw = attrs[key];
+    const accessor = config.accessors?.[key];
+    return accessor ? accessor(raw, attrs) : raw;
+};
+const runObservers = async (config, hook, model) => {
+    const observers = config.observers;
+    if (observers === undefined || observers.length === 0)
+        return;
+    for (const observer of observers) {
+        const fn = observer[hook];
+        if (typeof fn === 'function') {
+            // Observers intentionally run sequentially.
+            // eslint-disable-next-line no-await-in-loop
+            await fn(model);
         }
     }
 };
@@ -85,29 +105,36 @@ export const createModel = (config, attributes = {}) => {
             return model;
         },
         setAttribute: (key, value) => {
-            attrs[key] = castAttribute(config, key, value);
+            const mutator = config.mutators?.[key];
+            const nextValue = mutator ? mutator(value, attrs) : value;
+            attrs[key] = castAttribute(config, key, nextValue);
             return model;
         },
-        getAttribute: (key) => attrs[key],
+        getAttribute: (key) => applyAccessor(config, key, attrs),
         getAttributes: () => ({ ...attrs }),
         // remove in production - use saveChanges pattern
-        // eslint-disable-next-line @typescript-eslint/require-await
         async save() {
             if (db === undefined)
                 throw ErrorFactory.createDatabaseError('Database not initialized');
+            const isCreate = isExists === false;
+            await runObservers(config, 'saving', model);
+            await runObservers(config, isCreate ? 'creating' : 'updating', model);
             if (config.timestamps) {
                 attrs['created_at'] = attrs['created_at'] ?? new Date().toISOString();
                 attrs['updated_at'] = new Date().toISOString();
             }
             isExists = true;
             original = { ...attrs };
+            await runObservers(config, isCreate ? 'created' : 'updated', model);
+            await runObservers(config, 'saved', model);
             return true;
         },
         // remove in production - use delete pattern
-        // eslint-disable-next-line @typescript-eslint/require-await
         async delete() {
             if (!isExists || db === undefined)
                 return false;
+            await runObservers(config, 'deleting', model);
+            await runObservers(config, 'deleted', model);
             return true;
         },
         toJSON: () => createModelJSON(config, attrs),
@@ -130,11 +157,17 @@ export const query = (table, connection) => {
     const db = useDatabase(undefined, connection ?? DEFAULTS.CONNECTION);
     return QueryBuilder.create(table, db);
 };
+const buildSoftDeleteOptions = (config) => {
+    if (config.softDeletes !== true)
+        return undefined;
+    return { softDeleteColumn: 'deleted_at', softDeleteMode: 'exclude' };
+};
 /**
  * Find a model by ID
  */
 export const find = async (config, id) => {
-    const builder = query(config.table, config.connection);
+    const db = useDatabase(undefined, config.connection ?? DEFAULTS.CONNECTION);
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
     builder.where('id', '=', String(id)).limit(1);
     const result = await builder.first();
     if (result === null)
@@ -147,7 +180,8 @@ export const find = async (config, id) => {
  * Get all records for a model
  */
 export const all = async (config) => {
-    const builder = query(config.table, config.connection);
+    const db = useDatabase(undefined, config.connection ?? DEFAULTS.CONNECTION);
+    const builder = QueryBuilder.create(config.table, db, buildSoftDeleteOptions(config));
     const results = await builder.get();
     return results.map((result) => {
         const model = createModel(config, result);
@@ -187,7 +221,22 @@ export function define(config, methodsOrPlan) {
             const models = await all(cfg);
             return models.map((m) => attach(m));
         },
-        query: () => query(cfg.table, cfg.connection),
+        query: () => {
+            const db = useDatabase(undefined, cfg.connection ?? DEFAULTS.CONNECTION);
+            return QueryBuilder.create(cfg.table, db, buildSoftDeleteOptions(cfg));
+        },
+        scope: (name, ...args) => {
+            const scopes = cfg.scopes;
+            const fn = scopes?.[name];
+            if (typeof fn !== 'function') {
+                throw ErrorFactory.createConfigError(`Unknown query scope: ${name}`);
+            }
+            const builder = (() => {
+                const db = useDatabase(undefined, cfg.connection ?? DEFAULTS.CONNECTION);
+                return QueryBuilder.create(cfg.table, db, buildSoftDeleteOptions(cfg));
+            })();
+            return fn(builder, ...args);
+        },
         getTable: () => cfg.table,
         db: (connection) => createDefinedModel({ ...cfg, connection }),
     });

package/src/orm/QueryBuilder.d.ts

@@ -8,11 +8,19 @@ export interface WhereClause {
     operator: string;
     value: unknown;
 }
+export type SoftDeleteMode = 'exclude' | 'include' | 'only';
+export interface QueryBuilderOptions {
+    softDeleteColumn?: string;
+    softDeleteMode?: SoftDeleteMode;
+}
 export interface IQueryBuilder {
     select(...columns: string[]): IQueryBuilder;
     where(column: string, operator: string | number | boolean | null, value?: unknown): IQueryBuilder;
     andWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
     orWhere(column: string, operator: string, value?: unknown): IQueryBuilder;
+    withTrashed(): IQueryBuilder;
+    onlyTrashed(): IQueryBuilder;
+    withoutTrashed(): IQueryBuilder;
     join(table: string, on: string): IQueryBuilder;
     leftJoin(table: string, on: string): IQueryBuilder;
     orderBy(column: string, direction?: 'ASC' | 'DESC'): IQueryBuilder;
@@ -47,7 +55,7 @@ export declare const QueryBuilder: Readonly<{
     /**
      * Create a new query builder instance
      */
-    create(tableOrDb: string | IDatabase, db?: IDatabase): IQueryBuilder;
+    create(tableOrDb: string | IDatabase, db?: IDatabase, options?: QueryBuilderOptions): IQueryBuilder;
     /**
      * Ping the database connection.
      *

package/src/orm/QueryBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/orm/QueryBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC3E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IACnD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC;IACnE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,eAAe,IAAI,WAAW,EAAE,CAAC;IACjC,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAC7B,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,IAAI,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACxE,QAAQ,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,eAAe,IAAI,OAAO,CAAC;IAC3B,KAAK,IAAI,MAAM,CAAC;IAChB,aAAa,IAAI,OAAO,EAAE,CAAC;IAC3B,KAAK,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACxB;AAoTD;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;sBACe,MAAM,GAAG,SAAS,OAAO,SAAS,GAAG,aAAa;IAkBpE;;;;;OAKG;aACY,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;EAIxC,CAAC"}
+{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/orm/QueryBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC3E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1E,WAAW,IAAI,aAAa,CAAC;IAC7B,WAAW,IAAI,aAAa,CAAC;IAC7B,cAAc,IAAI,aAAa,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IACnD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC;IACnE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IACrC,eAAe,IAAI,WAAW,EAAE,CAAC;IACjC,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAC7B,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,IAAI,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACxE,QAAQ,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,eAAe,IAAI,OAAO,CAAC;IAC3B,KAAK,IAAI,MAAM,CAAC;IAChB,aAAa,IAAI,OAAO,EAAE,CAAC;IAC3B,KAAK,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACxB;AAgWD;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB;;OAEG;sBAEU,MAAM,GAAG,SAAS,OACxB,SAAS,YACL,mBAAmB,GAC3B,aAAa;IAyBhB;;;;;OAKG;aACY,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;EAIxC,CAAC"}

package/src/orm/QueryBuilder.js

@@ -117,6 +117,25 @@ const compileWhere = (conditions) => {
     });
     return { sql: ` WHERE ${clauses.join(' AND ')}`, parameters };
 };
+const buildSoftDeleteWhereClause = (column, mode) => {
+    const col = column.trim();
+    if (col.length === 0)
+        return null;
+    assertSafeIdentifierPath(col, 'soft delete column');
+    if (mode === 'include')
+        return null;
+    if (mode === 'only')
+        return { column: col, operator: 'IS NOT', value: null };
+    return { column: col, operator: 'IS', value: null };
+};
+const getEffectiveWhereConditions = (state) => {
+    if (state.softDelete === undefined)
+        return state.whereConditions;
+    const clause = buildSoftDeleteWhereClause(state.softDelete.column, state.softDelete.mode);
+    if (clause === null)
+        return state.whereConditions;
+    return [...state.whereConditions, clause];
+};
 /**
  * Build ORDER BY clause
  */
@@ -152,7 +171,7 @@ const buildSelectQuery = (state) => {
     }
     const columns = buildSelectClause(state.selectColumns);
     const fromClause = state.tableName.length > 0 ? ` FROM ${escapeIdentifier(state.tableName)}` : '';
-    const where = compileWhere(state.whereConditions);
+    const where = compileWhere(getEffectiveWhereConditions(state));
     const sql = `SELECT ${columns}${fromClause}${where.sql}${buildOrderByClause(state.orderByClause)}${buildLimitOffsetClause(state.limitValue, state.offsetValue)}`;
     return { sql, parameters: where.parameters };
 };
@@ -224,6 +243,33 @@ function createBuilder(state, db) {
         },
         andWhere: (column, operator, value) => builder.where(column, operator, value),
         orWhere: (column, operator, value) => builder.where(column, operator, value),
+        withTrashed: () => {
+            if (state.softDelete === undefined) {
+                state.softDelete = { column: 'deleted_at', mode: 'include' };
+            }
+            else {
+                state.softDelete.mode = 'include';
+            }
+            return builder;
+        },
+        onlyTrashed: () => {
+            if (state.softDelete === undefined) {
+                state.softDelete = { column: 'deleted_at', mode: 'only' };
+            }
+            else {
+                state.softDelete.mode = 'only';
+            }
+            return builder;
+        },
+        withoutTrashed: () => {
+            if (state.softDelete === undefined) {
+                state.softDelete = { column: 'deleted_at', mode: 'exclude' };
+            }
+            else {
+                state.softDelete.mode = 'exclude';
+            }
+            return builder;
+        },
         join: (tableJoin, on) => {
             state.joins.push({ table: tableJoin, on });
             return builder;
@@ -266,7 +312,7 @@ export const QueryBuilder = Object.freeze({
     /**
      * Create a new query builder instance
      */
-    create(tableOrDb, db) {
+    create(tableOrDb, db, options = {}) {
         const hasTable = typeof tableOrDb === 'string';
         const tableName = hasTable ? String(tableOrDb).trim() : '';
         const database = hasTable ? db : tableOrDb;
@@ -279,6 +325,12 @@ export const QueryBuilder = Object.freeze({
             selectColumns: ['*'],
             joins: [],
         };
+        if (options.softDeleteColumn !== undefined && options.softDeleteColumn.trim().length > 0) {
+            state.softDelete = {
+                column: options.softDeleteColumn.trim(),
+                mode: options.softDeleteMode ?? 'exclude',
+            };
+        }
         return createBuilder(state, database);
     },
     /**

package/src/scripts/TemplateSync.js

@@ -10,6 +10,7 @@ import { ErrorFactory } from '../exceptions/ZintrustError.js';
 import * as crypto from '../node-singletons/crypto.js';
 import fs from '../node-singletons/fs.js';
 import * as path from '../node-singletons/path.js';
+import * as nodePath from 'node:path';
 const __dirname = esmDirname(import.meta.url);
 const ROOT_DIR = path.resolve(__dirname, '../../');
 /**
@@ -115,9 +116,30 @@ const rewriteStarterTemplateImports = (relPath, content) => {
     if (!relPath.endsWith('.ts') && !relPath.endsWith('.tsx') && !relPath.endsWith('.mts')) {
         return content;
     }
+    const rewriteConfigAlias = (aliasSuffix) => {
+        const currentDir = nodePath.posix.dirname(relPath);
+        const from = currentDir === '.' ? '' : currentDir;
+        const target = aliasSuffix;
+        const relative = nodePath.posix.relative(from, target);
+        return relative.startsWith('.') ? relative : `./${relative}`;
+    };
     // Starter templates should import framework APIs from the public package surface,
     // not from internal path-alias modules that only exist in the framework repo.
     return (content
+        // Node-singletons are internal to this repo; starter templates should use Node built-ins.
+        .replaceAll("'@node-singletons/fs'", "'node:fs'")
+        .replaceAll('"@node-singletons/fs"', '"node:fs"')
+        .replaceAll("'@node-singletons/path'", "'node:path'")
+        .replaceAll('"@node-singletons/path"', '"node:path"')
+        // Starter project config/* should reference sibling config modules via relative imports.
+        .replaceAll(/(['"])@config\/([^'"]+)\1/g, (_m, quote, suffix) => {
+        const rewritten = rewriteConfigAlias(suffix);
+        return `${quote}${rewritten}${quote}`;
+    })
+        // Middleware imports are framework APIs; they must come from the public package.
+        .replaceAll(/(['"])@middleware\/[^'"]+\1/g, (_m, quote) => {
+        return `${quote}@zintrust/core${quote}`;
+    })
         .replaceAll("'@routing/Router'", "'@zintrust/core'")
         .replaceAll("'@orm/Database'", "'@zintrust/core'")
         .replaceAll("'@orm/QueryBuilder'", "'@zintrust/core'")
@@ -217,7 +239,7 @@ const syncStarterProjectTemplates = (params) => {
         templateDirRel: `${params.projectRoot}/config`,
         description: 'Starter project config/* (from src/config/*)',
         transformContent: rewriteStarterTemplateImports,
-        checksumSalt: 'starter-imports-v1',
+        checksumSalt: 'starter-imports-v4',
     });
     const s3 = syncProjectTemplateDir({
         checksums: params.checksums,

package/src/security/EncryptedEnvelope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * EncryptedEnvelope
+ *
+ * Framework-compatible encrypted payload envelope (PHP-style envelope).
+ *
+ * Format: base64(JSON({ iv, value, mac, tag }))
+ * - iv: base64
+ * - value: base64 ciphertext
+ * - mac: hex string (AES-CBC envelopes)
+ * - tag: base64 auth tag (AES-GCM envelopes)
+ */
+export type EncryptedEnvelopeCipher = 'aes-256-cbc' | 'aes-256-gcm';
+export type EncryptedEnvelopeCipherInput = EncryptedEnvelopeCipher | 'AES-256-CBC' | 'AES-256-GCM';
+export type EncryptedEnvelopePayload = {
+    iv: string;
+    value: string;
+    mac?: string;
+    tag?: string;
+};
+export type EncryptedEnvelopeSerializer<T> = {
+    serialize: (value: T) => string;
+    deserialize: (value: string) => T;
+};
+export type EncryptedEnvelopeKeyring = {
+    primaryKey: Uint8Array;
+    previousKeys: Uint8Array[];
+};
+export type EncryptedEnvelopeEnv = {
+    APP_KEY?: string;
+    APP_PREVIOUS_KEYS?: string;
+    ENCRYPTION_CIPHER?: string;
+};
+export declare const EncryptedEnvelope: Readonly<{
+    normalizeCipher: (cipher: EncryptedEnvelopeCipherInput) => EncryptedEnvelopeCipher;
+    /**
+     * Build a keyring from environment variables.
+     * - Uses APP_KEY
+     * - Supports APP_PREVIOUS_KEYS (comma-separated or JSON array)
+     */
+    keyringFromEnv(env?: EncryptedEnvelopeEnv): EncryptedEnvelopeKeyring;
+    /**
+     * Encrypt a UTF-8 string and return a framework-compatible base64(JSON) envelope.
+     */
+    encryptString(plaintext: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+    }): string;
+    /**
+     * Decrypt a framework-compatible base64(JSON) envelope to a UTF-8 string.
+     * Tries the primary key first, then previous keys.
+     */
+    decryptString(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+    }): string;
+    /**
+     * Encrypt arbitrary values using a caller-provided serializer.
+     * This supports encrypted payloads for frameworks that store serialized values.
+     */
+    encrypt<T>(value: T, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): string;
+    /**
+     * Decrypt into an arbitrary value using a caller-provided serializer.
+     */
+    decrypt<T>(encrypted: string, options: {
+        cipher: EncryptedEnvelopeCipherInput;
+        key: string;
+        previousKeys?: string[];
+        serializer: EncryptedEnvelopeSerializer<T>;
+    }): T;
+}>;
+export default EncryptedEnvelope;
+//# sourceMappingURL=EncryptedEnvelope.d.ts.map

package/src/security/EncryptedEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EncryptedEnvelope.d.ts","sourceRoot":"","sources":["../../../src/security/EncryptedEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AACpE,MAAM,MAAM,4BAA4B,GAAG,uBAAuB,GAAG,aAAa,GAAG,aAAa,CAAC;AAEnG,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAChC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,UAAU,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AA6LF,eAAO,MAAM,iBAAiB;8BA3LG,4BAA4B,KAAG,uBAAuB;IA8LrF;;;;OAIG;yBAEI,oBAAoB,GACxB,wBAAwB;IAe3B;;OAEG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAC7D,MAAM;IAgCT;;;OAGG;6BAEU,MAAM,WACR;QAAE,MAAM,EAAE,4BAA4B,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACtF,MAAM;IA0BT;;;OAGG;YACK,CAAC,SACA,CAAC,WACC;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,MAAM;IAQT;;OAEG;YACK,CAAC,aACI,MAAM,WACR;QACP,MAAM,EAAE,4BAA4B,CAAC;QACrC,GAAG,EAAE,MAAM,CAAC;QACZ,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;KAC5C,GACA,CAAC;EASJ,CAAC;AAEH,eAAe,iBAAiB,CAAC"}