@ismaelsoilet/synapsejs 1.9.0 → 1.11.1

package/src/core/query-builder.ts

@@ -38,10 +38,29 @@ export interface JoinClause {
   as?: string;
 }
 
+export interface AggregateItem {
+  fn: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';
+  column?: string;
+  as?: string;
+}
+
+export interface HavingAggregateCondition {
+  fn: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';
+  column?: string;
+  op: WhereOperator;
+  value?: unknown;
+}
+
+export type HavingInput = WhereCondition | HavingAggregateCondition | HavingAggregateCondition[];
+
 export interface QueryOptions<T = Record<string, unknown>> {
   select?: Array<keyof T | string>;
+  distinct?: boolean;
+  aggregations?: AggregateItem[];
   where?: WhereCondition;
   join?: JoinClause[];
+  groupBy?: string[] | string;
+  having?: HavingInput;
   orderBy?: Record<string, 'asc' | 'desc' | 'ASC' | 'DESC'> | string;
   limit?: number;
   offset?: number;
@@ -73,6 +92,8 @@ const VALID_WHERE_OPERATORS = new Set<string>([
   'BETWEEN'
 ]);
 
+const VALID_AGGREGATE_FUNCTIONS = new Set<string>(['COUNT', 'SUM', 'AVG', 'MIN', 'MAX']);
+
 export function sanitizeOperator(op: string): WhereOperator {
   const normalized = op.trim().toUpperCase();
   if (!VALID_WHERE_OPERATORS.has(normalized)) {
@@ -109,41 +130,114 @@ function normalizeWhere(where?: WhereCondition): WhereClauseItem[] {
   return items;
 }
 
+/** Compiles one expression and its operator into a parameterized SQL condition. */
+function compileCondition(expression: string, op: string, value: unknown, params: unknown[]): string {
+  const normalized = sanitizeOperator(op);
+
+  if (normalized === 'IS NULL' || normalized === 'IS NOT NULL') {
+    return `${expression} ${normalized}`;
+  }
+
+  if (normalized === 'IN' || normalized === 'NOT IN') {
+    const arr = Array.isArray(value) ? value : [value];
+    if (arr.length === 0) {
+      return normalized === 'IN' ? '1=0' : '1=1';
+    }
+
+    const placeholders = arr.map((entry) => {
+      params.push(entry);
+      return `$${params.length}`;
+    });
+
+    return `${expression} ${normalized} (${placeholders.join(', ')})`;
+  }
+
+  if (normalized === 'BETWEEN') {
+    const arr = Array.isArray(value) ? value : [];
+    if (arr.length !== 2) {
+      throw new Error(`BETWEEN operator requires an array of 2 values, received: ${JSON.stringify(value)}`);
+    }
+
+    params.push(arr[0]);
+    const p1 = `$${params.length}`;
+    params.push(arr[1]);
+    const p2 = `$${params.length}`;
+    return `${expression} BETWEEN ${p1} AND ${p2}`;
+  }
+
+  params.push(value);
+  return `${expression} ${normalized} $${params.length}`;
+}
+
 /** Compiles WhereClauseItem array into parameterized SQL condition strings */
 export function compileWhereClauses(whereItems: WhereClauseItem[], params: unknown[]): string[] {
+  return whereItems.map((item) => compileCondition(sanitizeIdentifier(item.column), item.op, item.value, params));
+}
+
+/**
+ * Compiles HAVING conditions. A condition that names an aggregation alias is
+ * compiled as the aggregate expression, so PostgreSQL (which rejects output
+ * aliases in HAVING) and SQLite receive the same portable SQL.
+ */
+function compileHaving(
+  having: HavingInput,
+  aggregations: AggregateItem[],
+  groupBy: string[] | string | undefined,
+  params: unknown[]
+): string[] {
+  const aliases = new Map<string, string>();
+  const groupedColumns = new Set<string>();
+
+  if (groupBy) {
+    const columns = Array.isArray(groupBy) ? groupBy : groupBy.split(',').map((column) => column.trim());
+    for (const column of columns) {
+      groupedColumns.add(sanitizeIdentifier(column.trim()));
+    }
+  }
+
+  for (const aggregation of aggregations) {
+    const fn = aggregation.fn.toUpperCase();
+    if (!VALID_AGGREGATE_FUNCTIONS.has(fn)) {
+      throw new Error(`Invalid aggregate function: "${aggregation.fn}"`);
+    }
+
+    const column = aggregation.column?.trim() || '*';
+    const expression = `${fn}(${column === '*' ? '*' : sanitizeIdentifier(column)})`;
+
+    if (aggregation.as) {
+      aliases.set(aggregation.as, expression);
+    }
+  }
+
+  const items: Array<WhereClauseItem | HavingAggregateCondition> = Array.isArray(having)
+    ? having
+    : typeof having === 'object' && having !== null && 'fn' in having
+      ? [having as HavingAggregateCondition]
+      : normalizeWhere(having as WhereCondition);
+
   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)}`);
+  for (const item of items) {
+    if ('fn' in item) {
+      const fn = item.fn.toUpperCase();
+      if (!VALID_AGGREGATE_FUNCTIONS.has(fn)) {
+        throw new Error(`Invalid aggregate function: "${item.fn}"`);
       }
-      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 column = item.column?.trim() || '*';
+      const expression = `${fn}(${column === '*' ? '*' : sanitizeIdentifier(column)})`;
+      conditions.push(compileCondition(expression, item.op, item.value, params));
+      continue;
     }
+
+    const aliasExpression = aliases.get(item.column);
+    const column = sanitizeIdentifier(item.column);
+
+    if (!aliasExpression && !groupedColumns.has(column)) {
+      throw new Error(`Invalid HAVING column: "${item.column}" must be a groupBy column or an aggregation alias`);
+    }
+
+    conditions.push(compileCondition(aliasExpression ?? column, item.op, item.value, params));
   }
 
   return conditions;
@@ -200,10 +294,28 @@ export function compileSelect(table: string, options?: QueryOptions): { sql: str
         return safeCol;
       })
     );
-  } else if (!options?.join || options.join.length === 0) {
-    selectCols.push('*');
-  } else {
-    selectCols.push(`${safeTable}.*`);
+  }
+
+  // Handle explicit aggregations
+  if (options?.aggregations && options.aggregations.length > 0) {
+    for (const agg of options.aggregations) {
+      const fn = agg.fn.toUpperCase();
+      if (!VALID_AGGREGATE_FUNCTIONS.has(fn)) {
+        throw new Error(`Invalid aggregate function: "${agg.fn}"`);
+      }
+      const rawCol = agg.column?.trim() || '*';
+      const col = rawCol === '*' ? '*' : sanitizeIdentifier(rawCol);
+      const alias = agg.as ? ` AS "${sanitizeIdentifier(agg.as)}"` : '';
+      selectCols.push(`${fn}(${col})${alias}`);
+    }
+  }
+
+  if (selectCols.length === 0) {
+    if (!options?.join || options.join.length === 0) {
+      selectCols.push('*');
+    } else {
+      selectCols.push(`${safeTable}.*`);
+    }
   }
 
   // Handle joins
@@ -238,7 +350,8 @@ export function compileSelect(table: string, options?: QueryOptions): { sql: str
     }
   }
 
-  let sql = `SELECT ${selectCols.join(', ')} FROM ${safeTable}`;
+  const distinctPrefix = options?.distinct ? 'DISTINCT ' : '';
+  let sql = `SELECT ${distinctPrefix}${selectCols.join(', ')} FROM ${safeTable}`;
   if (joinClauses.length > 0) {
     sql += ` ${joinClauses.join(' ')}`;
   }
@@ -252,6 +365,25 @@ export function compileSelect(table: string, options?: QueryOptions): { sql: str
     }
   }
 
+  // 3. GROUP BY clause
+  if (options?.groupBy) {
+    const groupCols = Array.isArray(options.groupBy)
+      ? options.groupBy
+      : options.groupBy.split(',').map((c) => c.trim());
+    const safeGroupCols = groupCols.map((c) => sanitizeIdentifier(c.trim())).filter(Boolean);
+    if (safeGroupCols.length > 0) {
+      sql += ` GROUP BY ${safeGroupCols.join(', ')}`;
+    }
+  }
+
+  // 4. HAVING clause
+  if (options?.having) {
+    const conditions = compileHaving(options.having, options.aggregations ?? [], options.groupBy, params);
+    if (conditions.length > 0) {
+      sql += ` HAVING ${conditions.join(' AND ')}`;
+    }
+  }
+
   // 3. ORDER BY clause
   if (options?.orderBy) {
     if (typeof options.orderBy === 'string') {

package/src/core/session-context.ts

@@ -13,6 +13,7 @@ export interface SessionContext {
   readonly tenantId?: string;
   readonly email?: string;
   readonly roles: string[];
+  readonly permissions?: string[];
   readonly isAuthenticated: boolean;
   readonly token?: string;
   readonly metadata?: Record<string, unknown>;
@@ -21,6 +22,7 @@ export interface SessionContext {
 export function AnonymousSession(tenantId?: string): SessionContext {
   return {
     roles: [],
+    permissions: [],
     isAuthenticated: false,
     tenantId
   };
@@ -31,6 +33,7 @@ export function createSession(data: {
   tenantId?: string;
   email?: string;
   roles?: string[];
+  permissions?: string[];
   token?: string;
   metadata?: Record<string, unknown>;
 }): SessionContext {
@@ -39,6 +42,7 @@ export function createSession(data: {
     tenantId: data.tenantId,
     email: data.email,
     roles: data.roles || ['user'],
+    permissions: data.permissions || [],
     isAuthenticated: true,
     token: data.token,
     metadata: data.metadata || {}
@@ -53,18 +57,55 @@ export function hasAnyRole(session: SessionContext, roles: string[]): boolean {
   return session.isAuthenticated && roles.some((r) => session.roles.includes(r));
 }
 
+export function hasPermission(session: SessionContext, permission: string): boolean {
+  if (!session.isAuthenticated) return false;
+
+  const adminBypass = process.env.SYNAPSE_RBAC_ADMIN_BYPASS !== 'false';
+
+  if (adminBypass && (session.roles.includes('admin') || session.roles.includes('superadmin'))) {
+    return true;
+  }
+
+  return Boolean(session.permissions?.includes(permission));
+}
+
+export function hasAllPermissions(session: SessionContext, permissions: string[]): boolean {
+  return session.isAuthenticated && permissions.every((p) => hasPermission(session, p));
+}
+
 export type AuthCheckResult = Result<SessionContext, 'UNAUTHORIZED' | 'FORBIDDEN'>;
 
-export function requireAuth(session?: SessionContext, requiredRoles?: string[]): AuthCheckResult {
+export interface AuthRequirements {
+  roles?: string[];
+  permissions?: string[];
+}
+
+export function requireAuth(session?: SessionContext, requirements?: string[] | AuthRequirements): AuthCheckResult {
   if (!session?.isAuthenticated) {
     return Err('UNAUTHORIZED');
   }
 
-  if (requiredRoles && requiredRoles.length > 0) {
-    const authorized = hasAnyRole(session, requiredRoles);
-    if (!authorized) {
+  if (!requirements) {
+    return Ok(session);
+  }
+
+  if (Array.isArray(requirements)) {
+    if (requirements.length > 0 && !hasAnyRole(session, requirements)) {
       return Err('FORBIDDEN');
     }
+    return Ok(session);
+  }
+
+  if (requirements.roles && requirements.roles.length > 0 && !hasAnyRole(session, requirements.roles)) {
+    return Err('FORBIDDEN');
+  }
+
+  if (
+    requirements.permissions &&
+    requirements.permissions.length > 0 &&
+    !hasAllPermissions(session, requirements.permissions)
+  ) {
+    return Err('FORBIDDEN');
   }
 
   return Ok(session);

package/src/core/session-token.ts

@@ -18,6 +18,8 @@ export interface SessionClaims {
   userId: string;
   roles: string[];
   tenantId?: string;
+  /** Fine-grained permissions carried by the signed token. */
+  permissions?: string[];
   /** Expiry, in seconds since the epoch. */
   exp: number;
 }
@@ -220,7 +222,7 @@ function constantTimeEquals(left: string, right: string): boolean {
 }
 
 export function signSessionToken(
-  claims: { userId: string; roles: string[]; tenantId?: string },
+  claims: { userId: string; roles: string[]; tenantId?: string; permissions?: string[] },
   secret: string,
   maxAgeSeconds = 86_400
 ): string {
@@ -229,6 +231,7 @@ export function signSessionToken(
       userId: claims.userId,
       roles: claims.roles,
       tenantId: claims.tenantId,
+      permissions: claims.permissions,
       exp: Math.floor(Date.now() / 1000) + maxAgeSeconds
     })
   );
@@ -269,6 +272,18 @@ export function verifySessionToken(
     return Err('INVALID_TOKEN');
   }
 
+  if (claims.permissions !== undefined) {
+    if (
+      !Array.isArray(claims.permissions) ||
+      claims.permissions.length > 100 ||
+      claims.permissions.some(
+        (permission) => typeof permission !== 'string' || permission.length === 0 || permission.length > 100
+      )
+    ) {
+      return Err('INVALID_TOKEN');
+    }
+  }
+
   if (claims.exp * 1000 < Date.now()) {
     return Err('EXPIRED_TOKEN');
   }

package/src/core/sqlite-client.ts

@@ -166,6 +166,26 @@ export class SqliteDatabaseClient implements DatabaseClient {
     return rows.length;
   }
 
+  async count(table: string, where?: WhereCondition): Promise<number> {
+    const { sql, params } = compileSelect(table, {
+      aggregations: [{ fn: 'COUNT', column: '*', as: 'total' }],
+      where
+    });
+    const row = await this.queryOne<{ total: number | string }>(sql, params);
+    return row ? Number(row.total) : 0;
+  }
+
+  async exists(table: string, where: WhereCondition): Promise<boolean> {
+    const { sql, params } = compileSelect(table, { select: ['1'], where, limit: 1 });
+    const row = await this.queryOne<Record<string, unknown>>(sql, params);
+
+    return row !== null;
+  }
+
+  async aggregate<T = Record<string, unknown>>(table: string, options: QueryOptions): Promise<T[]> {
+    return this.findMany<T>(table, options);
+  }
+
   async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
     if (this.txDepth > 0) {
       // Reentrant transaction: use SQLite SAVEPOINT