@ismaelsoilet/synapsejs 1.4.0 → 1.9.0

package/src/core/database-client.ts

@@ -1,8 +1,9 @@
 /**
  * SynapseJS - Database Context & Query Builder Abstraction
  *
- * Provides a clean, type-safe persistence contract without reflection-based ORM bloat.
- * Compatible with raw parameterized SQL, Kysely, and Drizzle query builders.
+ * Provides a clean, type-safe persistence contract without reflection-based ORM bloat:
+ * raw parameterized SQL plus a relational query builder, with no adapter for any other
+ * query builder.
  */
 
 export interface QueryResult<T = unknown> {
@@ -112,6 +113,24 @@ export interface DatabaseClient {
 /**
  * In-memory Mock Database Client for deterministic testing and PBT (Fast-Check).
  */
+/** Equality and `eq`/`in` matching, which is what the in-memory store can honour honestly. */
+function rowMatchesCondition(row: Record<string, unknown>, where: WhereCondition): boolean {
+  return Object.entries(where).every(([column, condition]) => {
+    const value = row[column];
+
+    if (condition !== null && typeof condition === 'object' && 'op' in (condition as Record<string, unknown>)) {
+      const { op, val } = condition as { op: string; val: unknown };
+
+      if (op === 'eq') return value === val;
+      if (op === 'in') return Array.isArray(val) && val.includes(value);
+
+      return false;
+    }
+
+    return value === condition;
+  });
+}
+
 export class MockDatabaseClient implements DatabaseClient {
   private tables: Map<string, Array<Record<string, unknown>>> = new Map();
   private queryHandlers: Array<{
@@ -228,18 +247,61 @@ export class MockDatabaseClient implements DatabaseClient {
   async update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition): Promise<T[]> {
     const { sql, params } = compileUpdate(table, data, where);
     const results = await this.query<T>(sql, params);
-    if (results.length > 0) return results;
-    return [data as T];
+
+    if (results.length > 0) {
+      return results;
+    }
+
+    // No row matched, so no row is returned: reporting the payload back would be a
+    // write that never happened.
+    const rows = this.tables.get(table);
+
+    if (!rows) {
+      return [];
+    }
+
+    const updated = rows.filter((row) => rowMatchesCondition(row, where));
+    for (const row of updated) {
+      Object.assign(row, data);
+    }
+
+    return updated as unknown as T[];
   }
 
   async delete(table: string, where: WhereCondition): Promise<number> {
     const { sql, params } = compileDelete(table, where);
     const results = await this.query(sql, params);
-    return results.length > 0 ? results.length : 1;
+
+    if (results.length > 0) {
+      return results.length;
+    }
+
+    // A delete that matched nothing removed nothing.
+    const rows = this.tables.get(table);
+
+    if (!rows) {
+      return 0;
+    }
+
+    const survivors = rows.filter((row) => !rowMatchesCondition(row, where));
+    const removed = rows.length - survivors.length;
+    this.tables.set(table, survivors);
+
+    return removed;
   }
 
   async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
-    return operation(this);
+    const snapshot = new Map(
+      Array.from(this.tables.entries()).map(([table, rows]) => [table, rows.map((row) => ({ ...row }))])
+    );
+
+    try {
+      return await operation(this);
+    } catch (error) {
+      // A rolled-back transaction discards the writes made inside it.
+      this.tables = snapshot;
+      throw error;
+    }
   }
 
   close(): void {}

package/src/core/index.ts

@@ -1,11 +1,13 @@
 export * from './action-context';
 export * from './action-definition';
+export * from './cache';
 export * from './config';
 export * from './database-client';
 export * from './database-factory';
 export * from './image-optimizer';
 export * from './jobs';
 export * from './machine-types';
+export * from './path-guard';
 export * from './postgres-client';
 export * from './postgres-queue';
 export * from './query-builder';
@@ -13,4 +15,7 @@ export * from './session-context';
 export * from './session-token';
 export * from './sqlite-client';
 export * from './storage';
+export * from './topics';
 export * from './validation';
+export * from './webhook-signature';
+export * from './websocket';

package/src/core/path-guard.ts

@@ -0,0 +1,105 @@
+/**
+ * SynapseJS - Path Segment Guard
+ *
+ * The single rule that decides whether caller-supplied input may become one
+ * segment of a filesystem path. Every write surface — slice scaffolding,
+ * shared-module scaffolding, application creation and the upload parser —
+ * passes its input through this validator before joining, so containment
+ * cannot hold on one path and be missing on a sibling.
+ *
+ * It rejects rather than rewrites: a silently sanitized name turns a traversal
+ * into "expected behaviour".
+ */
+
+import * as path from 'path';
+import { Err, Ok, type Result } from './machine-types';
+
+export const MAX_PATH_SEGMENT_LENGTH = 120;
+
+/** An ordinary name: alphanumeric start, then alphanumerics, dot, underscore or dash. */
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** The same rule as a pattern source, for schemas that declare the constraint. */
+export const PATH_SEGMENT_PATTERN = SEGMENT_PATTERN.source;
+
+export type PathSegmentErrorCode = 'INVALID_PATH_SEGMENT';
+
+/**
+ * Accepts a caller-supplied string only when it is one safe path segment.
+ *
+ * Rejections: separators, parent traversal, absolute prefixes, empty or
+ * blank segments, over-length input, and anything outside the plain-name
+ * pattern. Every write surface that joins caller input into a filesystem
+ * path applies exactly this rule.
+ */
+export function validatePathSegment(
+  raw: string | null | undefined,
+  maxLength: number = MAX_PATH_SEGMENT_LENGTH
+): Result<string, PathSegmentErrorCode> {
+  if (typeof raw !== 'string') {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  const segment = raw.trim();
+
+  if (!segment || segment.length > maxLength) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (segment.includes('/') || segment.includes('\\') || segment.includes('\0')) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (segment.includes('..')) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (path.isAbsolute(segment) || /^[A-Za-z]:/.test(segment)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  if (!SEGMENT_PATTERN.test(segment)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  return Ok(segment);
+}
+
+/**
+ * True only when `target` resolves to a location strictly inside `base`.
+ *
+ * This is the post-join assertion: character validation alone is defeated by
+ * a compound path that looks safe segment by segment, so the resolved target
+ * is compared against the resolved base before any write.
+ */
+export function isInsideBase(base: string, target: string): boolean {
+  const resolvedBase = path.resolve(base);
+  const resolvedTarget = path.resolve(target);
+  const relative = path.relative(resolvedBase, resolvedTarget);
+
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+/**
+ * Validates every segment, joins them onto `base` and asserts the resolved
+ * target stays inside it. The only way to turn caller input into a write path.
+ */
+export function resolveWithinBase(base: string, ...segments: string[]): Result<string, PathSegmentErrorCode> {
+  const resolvedBase = path.resolve(base);
+
+  for (const segment of segments) {
+    const validated = validatePathSegment(segment);
+
+    if (!validated.ok) {
+      return validated;
+    }
+  }
+
+  const target = path.join(resolvedBase, ...segments);
+
+  if (!isInsideBase(resolvedBase, target)) {
+    return Err('INVALID_PATH_SEGMENT');
+  }
+
+  return Ok(target);
+}

package/src/core/postgres-client.ts

@@ -21,6 +21,7 @@ import {
 export class PostgresDatabaseClient implements DatabaseClient {
   private client: postgres.Sql;
 
+  // biome-ignore lint/suspicious/noExplicitAny: external postgres.js options boundary
   constructor(connectionString: string, options?: postgres.Options<any>) {
     this.client = postgres(connectionString, {
       max: options?.max || 10,
@@ -34,6 +35,7 @@ export class PostgresDatabaseClient implements DatabaseClient {
 
   async query<T = unknown>(queryStr: string, params: unknown[] = []): Promise<T[]> {
     // postgres.js unsafe executes raw SQL with parameter bindings
+    // biome-ignore lint/suspicious/noExplicitAny: external postgres.js unsafe bindings boundary
     const result = await this.client.unsafe(queryStr, params as any[]);
     return result as unknown as T[];
   }
@@ -97,20 +99,24 @@ export class PostgresDatabaseClient implements DatabaseClient {
     const res = await this.client.begin(async (sqlTx) => {
       const txClient: DatabaseClient = {
         query: async <U = unknown>(q: string, p: unknown[] = []) => {
+          // biome-ignore lint/suspicious/noExplicitAny: external postgres.js unsafe bindings boundary
           const res = await sqlTx.unsafe(q, p as any[]);
           return res as unknown as U[];
         },
         queryOne: async <U = unknown>(q: string, p: unknown[] = []) => {
+          // biome-ignore lint/suspicious/noExplicitAny: external postgres.js unsafe bindings boundary
           const res = await sqlTx.unsafe(q, p as any[]);
           return (res[0] ?? null) as U | null;
         },
         sql: async <U = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => {
           const { text, params } = compileTaggedSql(strings, ...values);
+          // biome-ignore lint/suspicious/noExplicitAny: external postgres.js unsafe bindings boundary
           const res = await sqlTx.unsafe(text, params as any[]);
           return res as unknown as U[];
         },
         sqlOne: async <U = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => {
           const { text, params } = compileTaggedSql(strings, ...values);
+          // biome-ignore lint/suspicious/noExplicitAny: external postgres.js unsafe bindings boundary
           const res = await sqlTx.unsafe(text, params as any[]);
           return (res[0] ?? null) as U | null;
         },

package/src/core/postgres-queue.ts

@@ -136,9 +136,47 @@ export class PostgresQueueEngine {
     const now = Date.now();
     const staleThreshold = now - this.visibilityTimeoutMs;
 
+    // 1. Mover tarefas zumbi expiradas para a tabela de DLQ
+    const deadJobs = await this.db.query<JobRecord>(
+      `UPDATE _synapse_jobs
+       SET status = 'dlq', locked_at = NULL, updated_at = $1, last_error = 'Visibility timeout exceeded max attempts'
+       WHERE status = 'running' AND locked_at < $2 AND attempts >= max_attempts
+       RETURNING *;`,
+      [now, staleThreshold]
+    );
+
+    for (const deadJob of deadJobs) {
+      // `job_id` is NOT NULL in the table, and the id is derived from the job so a
+      // repeated recovery of the same zombie stays idempotent. A failure here is
+      // logged: swallowing it is how a dead-letter queue silently holds nothing.
+      const dlqId = `dlq_${deadJob.id}`;
+
+      try {
+        await this.db.query(
+          `INSERT INTO _synapse_jobs_dlq (id, job_id, name, payload, attempts, max_attempts, last_error, failed_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+           ON CONFLICT (id) DO UPDATE SET attempts = EXCLUDED.attempts, last_error = EXCLUDED.last_error, failed_at = EXCLUDED.failed_at;`,
+          [
+            dlqId,
+            deadJob.id,
+            deadJob.name,
+            deadJob.payload,
+            deadJob.attempts,
+            deadJob.max_attempts,
+            deadJob.last_error,
+            now
+          ]
+        );
+      } catch (error: unknown) {
+        this.logger.warn(
+          `[DLQ] Falha ao registrar o job ${deadJob.id} na dead letter queue: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+
     const rows = await this.db.query<JobRecord>(
       `UPDATE _synapse_jobs
-       SET status = 'running', locked_at = $1, updated_at = $1
+       SET status = 'running', locked_at = $1, updated_at = $1, attempts = attempts + 1
        WHERE id = (
          SELECT id FROM _synapse_jobs
          WHERE (status = 'pending' AND run_at <= $1)
@@ -201,8 +239,8 @@ export class PostgresQueueEngine {
       await this.db.query(
         `UPDATE _synapse_jobs
          SET status = 'completed', attempts = $1, locked_at = NULL, updated_at = $2, last_error = NULL
-         WHERE id = $3`,
-        [attempts, now, job.id]
+         WHERE id = $3 AND (locked_at = $4 OR locked_at IS NULL)`,
+        [attempts, now, job.id, job.locked_at]
       );
       return true;
     } catch (handlerErr: unknown) {
@@ -218,8 +256,8 @@ export class PostgresQueueEngine {
         await this.db.query(
           `UPDATE _synapse_jobs
            SET status = 'pending', attempts = $1, run_at = $2, locked_at = NULL, updated_at = $3, last_error = $4
-           WHERE id = $5`,
-          [attempts, nextRunAt, now, errorMsg, job.id]
+           WHERE id = $5 AND (locked_at = $6 OR locked_at IS NULL)`,
+          [attempts, nextRunAt, now, errorMsg, job.id, job.locked_at]
         );
       } else {
         await this.sendToDlq(job, attempts, `Esgotado limite de tentativas (${job.max_attempts}): ${errorMsg}`, now);
@@ -244,8 +282,8 @@ export class PostgresQueueEngine {
     await this.db.query(
       `UPDATE _synapse_jobs
        SET status = 'dlq', attempts = $1, locked_at = NULL, updated_at = $2, last_error = $3
-       WHERE id = $4`,
-      [attempts, now, errorMsg, job.id]
+       WHERE id = $4 AND (locked_at = $5 OR locked_at IS NULL)`,
+      [attempts, now, errorMsg, job.id, job.locked_at]
     );
 
     this.logger.warn(`[DLQ] Job ${job.name} (${job.id}) movido para Dead Letter Queue: ${dlqId}`);

package/src/core/query-builder.ts

@@ -56,6 +56,31 @@ export function sanitizeIdentifier(ident: string): string {
   return trimmed;
 }
 
+const VALID_WHERE_OPERATORS = new Set<string>([
+  '=',
+  '!=',
+  '<>',
+  '>',
+  '<',
+  '>=',
+  '<=',
+  'LIKE',
+  'ILIKE',
+  'IN',
+  'NOT IN',
+  'IS NULL',
+  'IS NOT NULL',
+  'BETWEEN'
+]);
+
+export function sanitizeOperator(op: string): WhereOperator {
+  const normalized = op.trim().toUpperCase();
+  if (!VALID_WHERE_OPERATORS.has(normalized)) {
+    throw new Error(`Invalid SQL operator: "${op}"`);
+  }
+  return normalized as WhereOperator;
+}
+
 /** Normalize WhereCondition into an array of WhereClauseItem */
 function normalizeWhere(where?: WhereCondition): WhereClauseItem[] {
   if (!where) return [];
@@ -70,6 +95,13 @@ function normalizeWhere(where?: WhereCondition): WhereClauseItem[] {
       items.push({ column, op: 'IS NULL' });
     } else if (Array.isArray(value)) {
       items.push({ column, op: 'IN', value });
+    } else if (typeof value === 'object' && value !== null && 'op' in value) {
+      const cond = value as { op: string; val?: unknown; value?: unknown };
+      items.push({
+        column,
+        op: cond.op as WhereOperator,
+        value: cond.val !== undefined ? cond.val : cond.value
+      });
     } else {
       items.push({ column, op: '=', value });
     }
@@ -77,6 +109,46 @@ function normalizeWhere(where?: WhereCondition): WhereClauseItem[] {
   return items;
 }
 
+/** Compiles WhereClauseItem array into parameterized SQL condition strings */
+export function compileWhereClauses(whereItems: WhereClauseItem[], params: unknown[]): string[] {
+  const conditions: string[] = [];
+
+  for (const item of whereItems) {
+    const col = sanitizeIdentifier(item.column);
+    const op = sanitizeOperator(item.op);
+
+    if (op === 'IS NULL' || op === 'IS NOT NULL') {
+      conditions.push(`${col} ${op}`);
+    } else if (op === 'IN' || op === 'NOT IN') {
+      const arr = Array.isArray(item.value) ? item.value : [item.value];
+      if (arr.length === 0) {
+        conditions.push(op === 'IN' ? '1=0' : '1=1');
+      } else {
+        const placeholders = arr.map((val) => {
+          params.push(val);
+          return `$${params.length}`;
+        });
+        conditions.push(`${col} ${op} (${placeholders.join(', ')})`);
+      }
+    } else if (op === 'BETWEEN') {
+      const arr = Array.isArray(item.value) ? item.value : [];
+      if (arr.length !== 2) {
+        throw new Error(`BETWEEN operator requires an array of 2 values, received: ${JSON.stringify(item.value)}`);
+      }
+      params.push(arr[0]);
+      const p1 = `$${params.length}`;
+      params.push(arr[1]);
+      const p2 = `$${params.length}`;
+      conditions.push(`${col} BETWEEN ${p1} AND ${p2}`);
+    } else {
+      params.push(item.value);
+      conditions.push(`${col} ${op} $${params.length}`);
+    }
+  }
+
+  return conditions;
+}
+
 /**
  * Maps flat prefixed columns (e.g. "customer_name") into nested objects ({ customer: { name } })
  */
@@ -174,42 +246,7 @@ export function compileSelect(table: string, options?: QueryOptions): { sql: str
   // 2. WHERE clause
   const whereItems = normalizeWhere(options?.where);
   if (whereItems.length > 0) {
-    const conditions: string[] = [];
-
-    for (const item of whereItems) {
-      const col = sanitizeIdentifier(item.column);
-      const op = item.op.toUpperCase() as WhereOperator;
-
-      if (op === 'IS NULL' || op === 'IS NOT NULL') {
-        conditions.push(`${col} ${op}`);
-      } else if (op === 'IN' || op === 'NOT IN') {
-        const arr = Array.isArray(item.value) ? item.value : [item.value];
-        if (arr.length === 0) {
-          // Empty IN clause: IN () is invalid SQL -> false / true condition
-          conditions.push(op === 'IN' ? '1=0' : '1=1');
-        } else {
-          const placeholders = arr.map((val) => {
-            params.push(val);
-            return `$${params.length}`;
-          });
-          conditions.push(`${col} ${op} (${placeholders.join(', ')})`);
-        }
-      } else if (op === 'BETWEEN') {
-        const arr = Array.isArray(item.value) ? item.value : [];
-        if (arr.length !== 2) {
-          throw new Error(`BETWEEN operator requires an array of 2 values, received: ${JSON.stringify(item.value)}`);
-        }
-        params.push(arr[0]);
-        const p1 = `$${params.length}`;
-        params.push(arr[1]);
-        const p2 = `$${params.length}`;
-        conditions.push(`${col} BETWEEN ${p1} AND ${p2}`);
-      } else {
-        params.push(item.value);
-        conditions.push(`${col} ${op} $${params.length}`);
-      }
-    }
-
+    const conditions = compileWhereClauses(whereItems, params);
     if (conditions.length > 0) {
       sql += ` WHERE ${conditions.join(' AND ')}`;
     }
@@ -299,18 +336,7 @@ export function compileUpdate(
     throw new Error(`Unconditional UPDATE on ${table} is blocked for safety. Provide a WHERE condition.`);
   }
 
-  const conditions: string[] = [];
-  for (const item of whereItems) {
-    const col = sanitizeIdentifier(item.column);
-    const op = item.op.toUpperCase() as WhereOperator;
-    if (op === 'IS NULL' || op === 'IS NOT NULL') {
-      conditions.push(`${col} ${op}`);
-    } else {
-      params.push(item.value);
-      conditions.push(`${col} ${op} $${params.length}`);
-    }
-  }
-
+  const conditions = compileWhereClauses(whereItems, params);
   sql += ` WHERE ${conditions.join(' AND ')} RETURNING *;`;
   return { sql, params };
 }
@@ -326,18 +352,7 @@ export function compileDelete(table: string, where: WhereCondition): { sql: stri
   }
 
   const params: unknown[] = [];
-  const conditions: string[] = [];
-  for (const item of whereItems) {
-    const col = sanitizeIdentifier(item.column);
-    const op = item.op.toUpperCase() as WhereOperator;
-    if (op === 'IS NULL' || op === 'IS NOT NULL') {
-      conditions.push(`${col} ${op}`);
-    } else {
-      params.push(item.value);
-      conditions.push(`${col} ${op} $${params.length}`);
-    }
-  }
-
+  const conditions = compileWhereClauses(whereItems, params);
   const sql = `DELETE FROM ${safeTable} WHERE ${conditions.join(' AND ')} RETURNING *;`;
   return { sql, params };
 }

package/src/core/session-context.ts

@@ -79,7 +79,7 @@ export function requireTenant(session?: SessionContext, expectedTenantId?: strin
     return Err('UNAUTHORIZED');
   }
 
-  if (expectedTenantId && session.tenantId && session.tenantId !== expectedTenantId) {
+  if (expectedTenantId && session.tenantId !== expectedTenantId) {
     return Err('FORBIDDEN');
   }