@ismaelsoilet/synapsejs 1.1.0

package/src/core/query-builder.ts

@@ -0,0 +1,343 @@
+/**
+ * SynapseJS - Isomorphic Query Builder & SQL Compiler
+ *
+ * Compiles declarative filter criteria, sorting, pagination and mutations
+ * into parameterized SQL ($1, $2, ...) compatible with both SQLite and PostgreSQL.
+ * Immune to SQL injection and free of heavy ORM runtime overhead.
+ */
+
+export type WhereOperator =
+  | '='
+  | '!='
+  | '<>'
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | 'LIKE'
+  | 'ILIKE'
+  | 'IN'
+  | 'NOT IN'
+  | 'IS NULL'
+  | 'IS NOT NULL'
+  | 'BETWEEN';
+
+export interface WhereClauseItem {
+  column: string;
+  op: WhereOperator;
+  value?: unknown;
+}
+
+export type WhereCondition = Record<string, unknown> | WhereClauseItem[];
+
+export interface JoinClause {
+  table: string;
+  on: Record<string, string>;
+  type?: 'LEFT' | 'INNER' | 'RIGHT';
+  select?: string[];
+  as?: string;
+}
+
+export interface QueryOptions<T = Record<string, unknown>> {
+  select?: Array<keyof T | string>;
+  where?: WhereCondition;
+  join?: JoinClause[];
+  orderBy?: Record<string, 'asc' | 'desc' | 'ASC' | 'DESC'> | string;
+  limit?: number;
+  offset?: number;
+}
+
+/** Sanitize SQL identifiers (table names, column names) to avoid injection */
+export function sanitizeIdentifier(ident: string): string {
+  const trimmed = ident.trim();
+  if (!/^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)?$/.test(trimmed)) {
+    throw new Error(`Invalid SQL identifier: "${ident}"`);
+  }
+  return trimmed;
+}
+
+/** Normalize WhereCondition into an array of WhereClauseItem */
+function normalizeWhere(where?: WhereCondition): WhereClauseItem[] {
+  if (!where) return [];
+
+  if (Array.isArray(where)) {
+    return where;
+  }
+
+  const items: WhereClauseItem[] = [];
+  for (const [column, value] of Object.entries(where)) {
+    if (value === null || value === undefined) {
+      items.push({ column, op: 'IS NULL' });
+    } else if (Array.isArray(value)) {
+      items.push({ column, op: 'IN', value });
+    } else {
+      items.push({ column, op: '=', value });
+    }
+  }
+  return items;
+}
+
+/**
+ * Maps flat prefixed columns (e.g. "customer_name") into nested objects ({ customer: { name } })
+ */
+export function nestJoinedRow<T>(row: Record<string, unknown>, joins?: JoinClause[]): T {
+  if (!joins || joins.length === 0 || !row || typeof row !== 'object') {
+    return row as T;
+  }
+
+  const result: Record<string, unknown> = { ...row };
+
+  for (const j of joins) {
+    const alias = j.as || j.table;
+    const prefix = `${alias}_`;
+    const nestedObj: Record<string, unknown> = {};
+    let hasNestedFields = false;
+
+    for (const [key, value] of Object.entries(row)) {
+      if (key.startsWith(prefix)) {
+        const fieldName = key.slice(prefix.length);
+        nestedObj[fieldName] = value;
+        hasNestedFields = true;
+      }
+    }
+
+    if (hasNestedFields) {
+      result[alias] = nestedObj;
+    }
+  }
+
+  return result as T;
+}
+
+/**
+ * Compiles a SELECT query with parameterized filters, joins, order, limit, and offset.
+ */
+export function compileSelect(table: string, options?: QueryOptions): { sql: string; params: unknown[] } {
+  const safeTable = sanitizeIdentifier(table);
+  const params: unknown[] = [];
+
+  // 1. SELECT columns
+  const selectCols: string[] = [];
+  if (options?.select && options.select.length > 0) {
+    selectCols.push(
+      ...options.select.map((col) => {
+        const safeCol = sanitizeIdentifier(String(col));
+        if (options?.join && options.join.length > 0 && !safeCol.includes('.')) {
+          return `${safeTable}.${safeCol} AS "${safeCol}"`;
+        }
+        return safeCol;
+      })
+    );
+  } else if (!options?.join || options.join.length === 0) {
+    selectCols.push('*');
+  } else {
+    selectCols.push(`${safeTable}.*`);
+  }
+
+  // Handle joins
+  const joinClauses: string[] = [];
+  if (options?.join && options.join.length > 0) {
+    for (const j of options.join) {
+      const joinType = (j.type || 'LEFT').toUpperCase();
+      if (!['LEFT', 'INNER', 'RIGHT'].includes(joinType)) {
+        throw new Error(`Unsupported JOIN type: "${j.type}"`);
+      }
+      const joinTable = sanitizeIdentifier(j.table);
+      const joinAlias = j.as ? sanitizeIdentifier(j.as) : joinTable;
+      const targetTableClause = j.as ? `${joinTable} AS ${joinAlias}` : joinTable;
+
+      const onConditions: string[] = [];
+      for (const [leftCol, rightCol] of Object.entries(j.on)) {
+        const left = sanitizeIdentifier(leftCol.includes('.') ? leftCol : `${safeTable}.${leftCol}`);
+        const right = sanitizeIdentifier(rightCol.includes('.') ? rightCol : `${joinAlias}.${rightCol}`);
+        onConditions.push(`${left} = ${right}`);
+      }
+
+      joinClauses.push(`${joinType} JOIN ${targetTableClause} ON ${onConditions.join(' AND ')}`);
+
+      if (j.select && j.select.length > 0) {
+        for (const col of j.select) {
+          const safeCol = sanitizeIdentifier(col);
+          const qualifiedCol = col.includes('.') ? safeCol : `${joinAlias}.${safeCol}`;
+          const alias = `${joinAlias}_${col.replace('.', '_')}`;
+          selectCols.push(`${qualifiedCol} AS "${alias}"`);
+        }
+      }
+    }
+  }
+
+  let sql = `SELECT ${selectCols.join(', ')} FROM ${safeTable}`;
+  if (joinClauses.length > 0) {
+    sql += ` ${joinClauses.join(' ')}`;
+  }
+
+  // 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}`);
+      }
+    }
+
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(' AND ')}`;
+    }
+  }
+
+  // 3. ORDER BY clause
+  if (options?.orderBy) {
+    if (typeof options.orderBy === 'string') {
+      const parts = options.orderBy.split(',').map((part) => {
+        const [col, dir] = part.trim().split(/\s+/);
+        const safeCol = sanitizeIdentifier(col);
+        const safeDir = dir && dir.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+        return `${safeCol} ${safeDir}`;
+      });
+      sql += ` ORDER BY ${parts.join(', ')}`;
+    } else {
+      const parts = Object.entries(options.orderBy).map(([col, dir]) => {
+        const safeCol = sanitizeIdentifier(col);
+        const safeDir = String(dir).toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+        return `${safeCol} ${safeDir}`;
+      });
+      if (parts.length > 0) {
+        sql += ` ORDER BY ${parts.join(', ')}`;
+      }
+    }
+  }
+
+  // 4. LIMIT & OFFSET
+  if (typeof options?.limit === 'number' && options.limit >= 0) {
+    params.push(options.limit);
+    sql += ` LIMIT $${params.length}`;
+  }
+
+  if (typeof options?.offset === 'number' && options.offset >= 0) {
+    params.push(options.offset);
+    sql += ` OFFSET $${params.length}`;
+  }
+
+  return { sql, params };
+}
+
+/**
+ * Compiles an INSERT query returning the created row.
+ */
+export function compileInsert(table: string, data: Record<string, unknown>): { sql: string; params: unknown[] } {
+  const safeTable = sanitizeIdentifier(table);
+  const keys = Object.keys(data);
+  if (keys.length === 0) {
+    throw new Error(`Cannot insert empty record into ${table}`);
+  }
+
+  const columns = keys.map(sanitizeIdentifier);
+  const params: unknown[] = [];
+  const placeholders = keys.map((key) => {
+    params.push(data[key]);
+    return `$${params.length}`;
+  });
+
+  const sql = `INSERT INTO ${safeTable} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *;`;
+  return { sql, params };
+}
+
+/**
+ * Compiles an UPDATE query returning the modified rows.
+ */
+export function compileUpdate(
+  table: string,
+  data: Record<string, unknown>,
+  where: WhereCondition
+): { sql: string; params: unknown[] } {
+  const safeTable = sanitizeIdentifier(table);
+  const keys = Object.keys(data);
+  if (keys.length === 0) {
+    throw new Error(`Cannot update record in ${table} with empty data`);
+  }
+
+  const params: unknown[] = [];
+  const setClauses = keys.map((key) => {
+    params.push(data[key]);
+    return `${sanitizeIdentifier(key)} = $${params.length}`;
+  });
+
+  let sql = `UPDATE ${safeTable} SET ${setClauses.join(', ')}`;
+
+  const whereItems = normalizeWhere(where);
+  if (whereItems.length === 0) {
+    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}`);
+    }
+  }
+
+  sql += ` WHERE ${conditions.join(' AND ')} RETURNING *;`;
+  return { sql, params };
+}
+
+/**
+ * Compiles a DELETE query returning count/rows.
+ */
+export function compileDelete(table: string, where: WhereCondition): { sql: string; params: unknown[] } {
+  const safeTable = sanitizeIdentifier(table);
+  const whereItems = normalizeWhere(where);
+  if (whereItems.length === 0) {
+    throw new Error(`Unconditional DELETE on ${table} is blocked for safety. Provide a WHERE condition.`);
+  }
+
+  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 sql = `DELETE FROM ${safeTable} WHERE ${conditions.join(' AND ')} RETURNING *;`;
+  return { sql, params };
+}

package/src/core/rpc-client.ts

@@ -0,0 +1,70 @@
+/**
+ * SynapseJS - Transparent RPC Client
+ *
+ * Consumed by generated client-side stubs. Keeps the zero-throw contract across
+ * the network boundary: a malformed or unreachable RPC becomes an Err value
+ * instead of an exception, and never a business error the caller must guess.
+ */
+
+import { Err } from './machine-types';
+
+export type RpcTransportError = 'RPC_MALFORMED' | 'RPC_UNREACHABLE';
+
+/**
+ * Transport-level failure, deliberately outside the slice's domain error union:
+ * a broken response is not a business outcome.
+ */
+export function rpcTransportFailure<R>(error: RpcTransportError): R {
+  return Err(error) as R;
+}
+
+function browserCredentials(): Record<string, string> {
+  const scope = globalThis as { document?: { cookie?: string } };
+  const cookie = scope.document?.cookie;
+
+  if (!cookie) {
+    return {};
+  }
+
+  const readCookie = (name: string): string | null => {
+    const entry = cookie.split('; ').find((item) => item.startsWith(`${name}=`));
+    return entry ? decodeURIComponent(entry.slice(name.length + 1)) : null;
+  };
+
+  const headers: Record<string, string> = {};
+  const token = readCookie('synapse_token');
+  const roles = readCookie('synapse_roles');
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  if (roles) {
+    headers['x-user-roles'] = roles;
+  }
+
+  return headers;
+}
+
+/**
+ * Calls a slice RPC endpoint and returns its Result payload verbatim.
+ * The response is shape-checked: anything without the `ok` discriminant is a
+ * transport failure rather than a value the caller would silently accept.
+ */
+export async function rpcCall<R>(endpoint: string, payload: unknown): Promise<R> {
+  try {
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...browserCredentials() },
+      body: JSON.stringify(payload)
+    });
+
+    const data = (await response.json().catch(() => null)) as unknown;
+
+    if (!data || typeof data !== 'object' || !('ok' in data)) {
+      return rpcTransportFailure<R>('RPC_MALFORMED');
+    }
+
+    return data as R;
+  } catch {
+    return rpcTransportFailure<R>('RPC_UNREACHABLE');
+  }
+}

package/src/core/session-context.ts

@@ -0,0 +1,87 @@
+/**
+ * SynapseJS - Session & Role-Based Access Control (RBAC) Context
+ *
+ * Provides explicit, deterministic security contracts for slices.
+ * Eliminates implicit global auth states by injecting SessionContext directly
+ * into server actions without throws or hidden reflection.
+ */
+
+import { Err, Ok, type Result } from './machine-types';
+
+export interface SessionContext {
+  readonly userId?: string;
+  readonly tenantId?: string;
+  readonly email?: string;
+  readonly roles: string[];
+  readonly isAuthenticated: boolean;
+  readonly token?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export function AnonymousSession(tenantId?: string): SessionContext {
+  return {
+    roles: [],
+    isAuthenticated: false,
+    tenantId
+  };
+}
+
+export function createSession(data: {
+  userId: string;
+  tenantId?: string;
+  email?: string;
+  roles?: string[];
+  token?: string;
+  metadata?: Record<string, unknown>;
+}): SessionContext {
+  return {
+    userId: data.userId,
+    tenantId: data.tenantId,
+    email: data.email,
+    roles: data.roles || ['user'],
+    isAuthenticated: true,
+    token: data.token,
+    metadata: data.metadata || {}
+  };
+}
+
+export function hasRole(session: SessionContext, role: string): boolean {
+  return session.isAuthenticated && session.roles.includes(role);
+}
+
+export function hasAnyRole(session: SessionContext, roles: string[]): boolean {
+  return session.isAuthenticated && roles.some((r) => session.roles.includes(r));
+}
+
+export type AuthCheckResult = Result<SessionContext, 'UNAUTHORIZED' | 'FORBIDDEN'>;
+
+export function requireAuth(session?: SessionContext, requiredRoles?: string[]): AuthCheckResult {
+  if (!session?.isAuthenticated) {
+    return Err('UNAUTHORIZED');
+  }
+
+  if (requiredRoles && requiredRoles.length > 0) {
+    const authorized = hasAnyRole(session, requiredRoles);
+    if (!authorized) {
+      return Err('FORBIDDEN');
+    }
+  }
+
+  return Ok(session);
+}
+
+/**
+ * Asserts that the session is authenticated and associated with the expected tenant ID,
+ * returning Err('FORBIDDEN') to protect against IDOR (Insecure Direct Object Reference) violations.
+ */
+export function requireTenant(session?: SessionContext, expectedTenantId?: string): AuthCheckResult {
+  if (!session?.isAuthenticated) {
+    return Err('UNAUTHORIZED');
+  }
+
+  if (expectedTenantId && session.tenantId && session.tenantId !== expectedTenantId) {
+    return Err('FORBIDDEN');
+  }
+
+  return Ok(session);
+}

package/src/core/session-cookie.ts

@@ -0,0 +1,81 @@
+/**
+ * SynapseJS - Session Cookie (browser side)
+ *
+ * The server derives the session from the signature; the browser is what carries
+ * the token. These are the two calls a login screen needs — store after a
+ * successful login, clear to log out.
+ *
+ * Nothing here touches `process.env`, `Bun.` or the database, so it stays valid
+ * inside a client bundle. `document` is reached through `globalThis` on purpose:
+ * the framework typechecks without the DOM library, and the splitter would have
+ * no reason to keep a DOM-typed module out of the browser anyway.
+ */
+
+export const SESSION_COOKIE = 'synapse_token';
+export const ROLES_COOKIE = 'synapse_roles';
+
+/** Sessions last half a day unless the slice that signs them says otherwise. */
+export const DEFAULT_SESSION_MAX_AGE_SECONDS = 43_200;
+
+type CookieScope = { document?: { cookie?: string } };
+
+function scope(): CookieScope {
+  return globalThis as CookieScope;
+}
+
+/**
+ * One cookie, in the shape the runtime reads: path-wide, lax (so a cross-site
+ * form post does not carry it) and with an explicit lifetime.
+ */
+export function sessionCookie(name: string, value: string, maxAgeSeconds: number): string {
+  return `${name}=${encodeURIComponent(value)}; Path=/; Max-Age=${maxAgeSeconds}; SameSite=Lax`;
+}
+
+/**
+ * Stores the token the login action returned, plus the roles the UI may read
+ * without asking the server. The roles cookie is a convenience for rendering —
+ * the server ignores it whenever a session secret is configured and always
+ * takes the roles from the signed claims.
+ */
+export function storeSession(
+  token: string,
+  roles: string[] = [],
+  maxAgeSeconds = DEFAULT_SESSION_MAX_AGE_SECONDS
+): void {
+  const target = scope().document;
+  if (!target) {
+    return;
+  }
+
+  target.cookie = sessionCookie(SESSION_COOKIE, token, maxAgeSeconds);
+  target.cookie = sessionCookie(ROLES_COOKIE, roles.join(','), maxAgeSeconds);
+}
+
+/** Logs out: both cookies expire immediately. The server keeps no session state to clear. */
+export function clearSession(): void {
+  const target = scope().document;
+  if (!target) {
+    return;
+  }
+
+  target.cookie = sessionCookie(SESSION_COOKIE, '', 0);
+  target.cookie = sessionCookie(ROLES_COOKIE, '', 0);
+}
+
+/** The roles the current cookie advertises. Rendering aid, never an authorization source. */
+export function currentRoles(): string[] {
+  const cookie = scope().document?.cookie;
+  if (!cookie) {
+    return [];
+  }
+
+  const entry = cookie.split('; ').find((item) => item.startsWith(`${ROLES_COOKIE}=`));
+  if (!entry) {
+    return [];
+  }
+
+  return decodeURIComponent(entry.slice(ROLES_COOKIE.length + 1))
+    .split(',')
+    .map((role) => role.trim())
+    .filter((role) => role.length > 0);
+}