@zintrust/core 0.1.15 → 0.1.16

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/PasswordResetTokenBroker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Password Reset Token Broker
+ *
+ * Framework-agnostic, storage-pluggable password reset token flow.
+ *
+ * - Generates high-entropy tokens for a given identifier (usually an email).
+ * - Stores only a SHA-256 hash of the token (one active token per identifier).
+ * - Supports verification and one-time consumption.
+ */
+export interface PasswordResetTokenRecord {
+    identifier: string;
+    tokenHash: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+export interface IPasswordResetTokenStore {
+    set(record: PasswordResetTokenRecord): void | Promise<void>;
+    get(identifier: string): PasswordResetTokenRecord | null | Promise<PasswordResetTokenRecord | null>;
+    delete(identifier: string): void | Promise<void>;
+    cleanup?(now?: Date): number | Promise<number>;
+    clear?(): void | Promise<void>;
+}
+export interface IPasswordResetTokenBroker {
+    createToken(identifier: string): Promise<string>;
+    verifyToken(identifier: string, token: string): Promise<boolean>;
+    consumeToken(identifier: string, token: string): Promise<boolean>;
+}
+export interface PasswordResetTokenBrokerOptions {
+    store?: IPasswordResetTokenStore;
+    ttlMs?: number;
+    tokenBytes?: number;
+    now?: () => Date;
+}
+export interface PasswordResetTokenBrokerType {
+    create(options?: PasswordResetTokenBrokerOptions): IPasswordResetTokenBroker;
+    createInMemoryStore(): IPasswordResetTokenStore;
+}
+export declare const PasswordResetTokenBroker: PasswordResetTokenBrokerType;
+//# sourceMappingURL=PasswordResetTokenBroker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PasswordResetTokenBroker.d.ts","sourceRoot":"","sources":["../../../src/security/PasswordResetTokenBroker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,GAAG,CACD,UAAU,EAAE,MAAM,GACjB,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,+BAA+B;IAC9C,KAAK,CAAC,EAAE,wBAAwB,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,OAAO,CAAC,EAAE,+BAA+B,GAAG,yBAAyB,CAAC;IAC7E,mBAAmB,IAAI,wBAAwB,CAAC;CACjD;AAmFD,eAAO,MAAM,wBAAwB,EAAE,4BAGrC,CAAC"}

package/src/security/PasswordResetTokenBroker.js

@@ -0,0 +1,131 @@
+/**
+ * Password Reset Token Broker
+ *
+ * Framework-agnostic, storage-pluggable password reset token flow.
+ *
+ * - Generates high-entropy tokens for a given identifier (usually an email).
+ * - Stores only a SHA-256 hash of the token (one active token per identifier).
+ * - Supports verification and one-time consumption.
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createHash, randomBytes } from '../node-singletons/crypto.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_TOKEN_BYTES = 32; // 256 bits
+const createInMemoryStore = () => {
+    const map = new Map();
+    return {
+        set(record) {
+            map.set(record.identifier, record);
+        },
+        get(identifier) {
+            return map.get(identifier) ?? null;
+        },
+        delete(identifier) {
+            map.delete(identifier);
+        },
+        cleanup(now = new Date()) {
+            let removed = 0;
+            for (const [identifier, record] of map.entries()) {
+                if (now.getTime() > record.expiresAt.getTime()) {
+                    map.delete(identifier);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+        clear() {
+            map.clear();
+        },
+    };
+};
+const create = (options = {}) => {
+    const store = options.store ?? createInMemoryStore();
+    const ttlMs = normalizeTtlMs(options.ttlMs ?? DEFAULT_TTL_MS);
+    const tokenBytes = normalizeTokenBytes(options.tokenBytes ?? DEFAULT_TOKEN_BYTES);
+    const now = options.now ?? (() => new Date());
+    return {
+        async createToken(identifier) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const token = randomBytes(tokenBytes).toString('hex');
+            const tokenHash = sha256Hex(token);
+            const createdAt = now();
+            const expiresAt = new Date(createdAt.getTime() + ttlMs);
+            await store.set({ identifier: normalizedIdentifier, tokenHash, createdAt, expiresAt });
+            return token;
+        },
+        async verifyToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const normalizedToken = normalizeToken(token);
+            const record = await store.get(normalizedIdentifier);
+            if (record === null)
+                return false;
+            if (isExpired(record, now())) {
+                await store.delete(normalizedIdentifier);
+                return false;
+            }
+            const computed = sha256Hex(normalizedToken);
+            return timingSafeEquals(record.tokenHash, computed);
+        },
+        async consumeToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const ok = await this.verifyToken(normalizedIdentifier, token);
+            if (!ok)
+                return false;
+            await store.delete(normalizedIdentifier);
+            return true;
+        },
+    };
+};
+export const PasswordResetTokenBroker = Object.freeze({
+    create,
+    createInMemoryStore,
+});
+function normalizeIdentifier(identifier) {
+    if (typeof identifier !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    return trimmed;
+}
+function normalizeToken(token) {
+    if (typeof token !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    const trimmed = token.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    return trimmed;
+}
+function normalizeTtlMs(ttlMs) {
+    const value = Number.isFinite(ttlMs) ? Math.trunc(ttlMs) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset TTL', { ttlMs });
+    }
+    return value;
+}
+function normalizeTokenBytes(tokenBytes) {
+    const value = Number.isFinite(tokenBytes) ? Math.trunc(tokenBytes) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset token bytes', { tokenBytes });
+    }
+    return value;
+}
+function isExpired(record, now) {
+    return now.getTime() > record.expiresAt.getTime();
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function timingSafeEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+    }
+    return result === 0;
+}

package/src/session/SessionManager.d.ts

@@ -0,0 +1,39 @@
+export type SessionData = Record<string, unknown>;
+export interface ISession {
+    id: string;
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    forget(key: string): void;
+    all(): SessionData;
+    clear(): void;
+}
+export interface ISessionManager {
+    getIdFromCookieHeader(cookieHeader: string | undefined): string | undefined;
+    getIdFromRequest(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context?: Record<string, unknown>;
+    }): string | undefined;
+    ensureSessionId(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context: Record<string, unknown>;
+    }, res: {
+        getHeader: (name: string) => unknown;
+        setHeader: (name: string, value: string | string[]) => unknown;
+    }): Promise<string>;
+    get(sessionId: string): ISession;
+    destroy(sessionId: string): void;
+    cleanup(): number;
+}
+export interface SessionManagerOptions {
+    cookieName?: string;
+    headerName?: string;
+    ttlMs?: number;
+}
+export declare const SessionManager: Readonly<{
+    create(options?: SessionManagerOptions): ISessionManager;
+}>;
+export default SessionManager;
+//# sourceMappingURL=SessionManager.d.ts.map

package/src/session/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../../src/session/SessionManager.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,IAAI,WAAW,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5E,gBAAgB,CAAC,GAAG,EAAE;QACpB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,MAAM,GAAG,SAAS,CAAC;IACvB,eAAe,CACb,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,EACD,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC;KAChE,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyHD,eAAO,MAAM,cAAc;qBACT,qBAAqB,GAAQ,eAAe;EA2E5D,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/session/SessionManager.js

@@ -0,0 +1,149 @@
+import { generateSecureJobId } from '../common/uuid.js';
+const DEFAULT_OPTIONS = {
+    cookieName: 'ZIN_SESSION_ID',
+    headerName: 'x-session-id',
+    ttlMs: 7 * 24 * 60 * 60 * 1000,
+};
+function parseCookies(cookieHeader) {
+    const list = {};
+    if (cookieHeader.length === 0)
+        return list;
+    cookieHeader.split(';').forEach((cookie) => {
+        const parts = cookie.split('=');
+        const name = parts.shift()?.trim();
+        const value = parts.join('=');
+        if (name !== null && name !== undefined)
+            list[name] = decodeURIComponent(value);
+    });
+    return list;
+}
+function appendSetCookie(res, cookie) {
+    const existing = res.getHeader('Set-Cookie');
+    if (existing === undefined) {
+        res.setHeader('Set-Cookie', cookie);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        const existingCookies = existing.map(String);
+        res.setHeader('Set-Cookie', [...existingCookies, cookie]);
+        return;
+    }
+    if (typeof existing === 'string') {
+        res.setHeader('Set-Cookie', [existing, cookie]);
+        return;
+    }
+    res.setHeader('Set-Cookie', cookie);
+}
+function buildSessionCookie(cookieName, sessionId) {
+    // Keep this minimal; callers can override behavior later.
+    // HttpOnly prevents JS access; SameSite=Lax is a reasonable default for app sessions.
+    return `${cookieName}=${encodeURIComponent(sessionId)}; Path=/; HttpOnly; SameSite=Lax`;
+}
+function createSessionApi(sessions, sessionId, ttlMs) {
+    const withoutKey = (data, key) => {
+        if (!Object.prototype.hasOwnProperty.call(data, key))
+            return data;
+        const record = data;
+        const { [key]: _removed, ...rest } = record;
+        return rest;
+    };
+    const ensureStored = () => {
+        const existing = sessions.get(sessionId);
+        const now = Date.now();
+        if (existing !== undefined && existing.expiresAt > now) {
+            return existing;
+        }
+        const created = { data: {}, expiresAt: now + ttlMs };
+        sessions.set(sessionId, created);
+        return created;
+    };
+    return {
+        id: sessionId,
+        get(key) {
+            return ensureStored().data[key];
+        },
+        set(key, value) {
+            const stored = ensureStored();
+            stored.data[key] = value;
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+        has(key) {
+            return Object.prototype.hasOwnProperty.call(ensureStored().data, key);
+        },
+        forget(key) {
+            const stored = ensureStored();
+            stored.data = withoutKey(stored.data, key);
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+        all() {
+            return { ...ensureStored().data };
+        },
+        clear() {
+            const stored = ensureStored();
+            stored.data = {};
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+    };
+}
+export const SessionManager = Object.freeze({
+    create(options = {}) {
+        const config = { ...DEFAULT_OPTIONS, ...options };
+        const sessions = new Map();
+        return {
+            getIdFromCookieHeader(cookieHeader) {
+                if (cookieHeader === undefined || cookieHeader.length === 0)
+                    return undefined;
+                const cookies = parseCookies(cookieHeader);
+                return cookies[config.cookieName];
+            },
+            getIdFromRequest(req) {
+                const cookieHeader = req.getHeader('cookie');
+                if (typeof cookieHeader === 'string') {
+                    const fromCookie = this.getIdFromCookieHeader(cookieHeader);
+                    if (fromCookie !== undefined)
+                        return fromCookie;
+                }
+                const fromHeader = req.getHeader(config.headerName);
+                if (typeof fromHeader === 'string' && fromHeader.length > 0)
+                    return fromHeader;
+                if (typeof req.sessionId === 'string' && req.sessionId.length > 0)
+                    return req.sessionId;
+                const fromContext = req.context?.['sessionId'];
+                if (typeof fromContext === 'string' && fromContext.length > 0)
+                    return fromContext;
+                return undefined;
+            },
+            async ensureSessionId(req, res) {
+                const existing = this.getIdFromRequest(req);
+                const sessionId = existing ??
+                    (await Promise.resolve(generateSecureJobId('SessionManager: secure crypto API not available to generate a session id')));
+                req.context['sessionId'] = sessionId;
+                // If the cookie is missing, set it.
+                const cookieHeader = req.getHeader('cookie');
+                const fromCookie = typeof cookieHeader === 'string' ? this.getIdFromCookieHeader(cookieHeader) : undefined;
+                if (fromCookie === undefined) {
+                    appendSetCookie(res, buildSessionCookie(config.cookieName, sessionId));
+                }
+                return sessionId;
+            },
+            get(sessionId) {
+                return createSessionApi(sessions, sessionId, config.ttlMs);
+            },
+            destroy(sessionId) {
+                sessions.delete(sessionId);
+            },
+            cleanup() {
+                const now = Date.now();
+                let removed = 0;
+                for (const [id, stored] of sessions.entries()) {
+                    if (stored.expiresAt <= now) {
+                        sessions.delete(id);
+                        removed++;
+                    }
+                }
+                return removed;
+            },
+        };
+    },
+});
+export default SessionManager;

package/src/session/index.d.ts

@@ -0,0 +1,3 @@
+export { SessionManager } from './SessionManager';
+export type { ISession, ISessionManager, SessionData, SessionManagerOptions } from './SessionManager';
+//# sourceMappingURL=index.d.ts.map