@ismaelsoilet/synapsejs 1.4.0 → 1.9.0

package/src/compiler/slice-splitter.ts

@@ -42,7 +42,12 @@ export interface SplitResult {
   artifacts: SplitArtifact[];
 }
 
-export type SplitErrorCode = 'SLICE_NOT_FOUND' | 'SLICE_IMPORTS_SLICE' | 'NO_ROOTS' | 'UNPARSED';
+export type SplitErrorCode =
+  | 'SLICE_NOT_FOUND'
+  | 'SLICE_IMPORTS_SLICE'
+  | 'NO_ROOTS'
+  | 'UNPARSED'
+  | 'SERVER_VALUE_IN_CLIENT';
 
 export interface SplitError {
   code: SplitErrorCode;
@@ -67,10 +72,14 @@ export interface SplitVerification {
 const CLIENT_ROOTS = [...COMPONENT_SUFFIXES];
 const TEST_ONLY_NAMES: readonly string[] = [...TEST_ONLY_EXPORTS];
 
-const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
+/** The expressions that must never survive into a client bundle. Exported so the
+ * linear-time guarantee can be asserted directly against each of them. */
+export const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
   // `SELECT ... FROM` e não `SELECT` seguido de qualquer palavra: sem o FROM, a
   // tag HTML `<select id="x">` de um formulário casava como vazamento de SQL.
-  { label: 'SELECT statement', pattern: /\bSELECT\s+[\w*"`][\w*"`.,\s]*\bFROM\b/i },
+  // O quantificador é limitado (uma janela fixa, não `*`): um bundle grande com
+  // muitos `SELECT` sem `FROM` fazia o motor retroceder sobre o texto inteiro.
+  { label: 'SELECT statement', pattern: /\bSELECT\s[\w*"`.,\s]{0,4096}?\bFROM\b/i },
   { label: 'INSERT statement', pattern: /\bINSERT\s+INTO\b/i },
   { label: 'UPDATE statement', pattern: /\bUPDATE\s+\w+\s+SET\b/i },
   { label: 'DELETE statement', pattern: /\bDELETE\s+FROM\b/i },
@@ -82,11 +91,23 @@ const SERVER_ONLY_PATTERNS: Array<{ label: string; pattern: RegExp }> = [
   { label: 'test runner import', pattern: /from\s+['"]bun:test['"]/ },
   { label: 'process.env access', pattern: /\bprocess\s*(?:\.\s*env|\[\s*['"]env['"]\s*\])/ },
   { label: 'process destructuring', pattern: /\b(?:const|let|var)\s*\{[^}]*\benv\b[^}]*\}\s*=\s*process\b/ },
-  { label: 'Bun global', pattern: /\bBun\./ },
+  { label: 'Bun global', pattern: /\bBun(?:\.|\s*\[)/ },
+  {
+    label: 'globalThis server access',
+    pattern: /\bglobalThis\s*(?:\.\s*(?:process|Bun)|\[\s*['"](?:process|Bun)['"]\s*\])/
+  },
   {
     label: 'node server module import',
     pattern: /from\s+['"](?:node:)?(?:fs|child_process|cluster|dgram|dns|net|tls|v8|vm)['"]/
   },
+  {
+    label: 'server dynamic import',
+    pattern: /\bimport\s*\(\s*['"](?:node:)?(?:fs|child_process|sqlite|postgres|bun|cluster|net|tls)['"]/
+  },
+  {
+    label: 'server require leak',
+    pattern: /\brequire\s*\(\s*['"](?:node:)?(?:fs|child_process|sqlite|postgres|bun|cluster|net|tls)['"]/
+  },
   { label: 'dynamic code evaluation', pattern: /\b(?:eval|new\s+Function)\s*\(/ }
 ];
 
@@ -495,6 +516,20 @@ function unwrapPromiseType(typeText: string): string {
   return match ? match[1].trim() : `Awaited<${typeText}>`;
 }
 
+/**
+ * A wire stub describes a server *function*. A server-owned value that a component
+ * references has no wire form, so the caller must fail with a diagnostic instead of
+ * emitting a stub that would call the endpoint as if it were an action.
+ */
+function isStubCandidate(entry: DeclEntry): boolean {
+  return (
+    ts.isFunctionDeclaration(entry.node) ||
+    ts.isFunctionExpression(entry.node) ||
+    ts.isArrowFunction(entry.node) ||
+    ts.isMethodDeclaration(entry.node)
+  );
+}
+
 function renderRpcStub(entry: DeclEntry, endpoint: string, sourceFile: ts.SourceFile): string {
   const fn = entry.node as ts.FunctionDeclaration;
   const payload = fn.parameters[0];
@@ -603,7 +638,8 @@ export function splitSlice(sliceFilePath: string, baseDir: string = process.cwd(
       message:
         `Uma fatia não importa outra: ${path.basename(sliceFilePath)} alcança ` +
         `${path.relative(process.cwd(), illegalImport)}. Mova o código comum para ` +
-        'src/shared/<nome>.ts, receba o db por parâmetro e chame de dentro das duas fatias.',
+        'src/shared/<nome>.ts, receba o db por parâmetro e chame de dentro das duas fatias. ' +
+        'Dica: use `synapse new-shared <nome>` para criar um módulo compartilhado seguro em src/shared/.',
       candidates: [illegalImport]
     });
   }
@@ -699,6 +735,27 @@ export function splitSlice(sliceFilePath: string, baseDir: string = process.cwd(
   const sliceName = path.basename(sliceFilePath, '.slice.tsx');
   const relativePath = path.relative(baseDir, sliceFilePath);
   const endpoint = `/_synapse/rpc/${sliceName}`;
+
+  const serverValueInClient = stubbedKeys.find((key) => {
+    const entry = entries.get(key);
+
+    return entry ? !isStubCandidate(entry) : false;
+  });
+
+  if (serverValueInClient) {
+    const entry = entries.get(serverValueInClient) as DeclEntry;
+
+    return Err({
+      code: 'SERVER_VALUE_IN_CLIENT',
+      message:
+        `O componente de ${path.basename(sliceFilePath)} referencia '${serverValueInClient}', ` +
+        `que é um valor do servidor (${ts.SyntaxKind[entry.node.kind]}) e não uma action: não existe ` +
+        `forma de transportá-lo pelo endpoint RPC. Mova o valor para um módulo em src/shared/, ` +
+        `importe-o de 'synapsejs/client', ou limite-se a declará-lo no servidor.`,
+      candidates: [serverValueInClient]
+    });
+  }
+
   const artifacts: SplitArtifact[] = [];
   const outDir = artifactDirectory(baseDir, sliceName);
   const sourceDir = path.dirname(sliceFilePath);
@@ -831,8 +888,12 @@ export function verifySplit(result: SplitResult, outDir: string): SplitVerificat
       leaks.push('pacote-raiz-no-cliente');
     }
 
+    const normalizedCode = clientArtifact.code.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) =>
+      String.fromCharCode(parseInt(hex, 16))
+    );
+
     for (const { label, pattern } of SERVER_ONLY_PATTERNS) {
-      if (pattern.test(clientArtifact.code)) {
+      if (pattern.test(clientArtifact.code) || pattern.test(normalizedCode)) {
         leaks.push(label);
       }
     }

package/src/compiler/slice-templates.ts

@@ -820,6 +820,9 @@ export const sliceSchema = \`
     roles TEXT NOT NULL DEFAULT 'user',
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
+
+  -- down:
+  DROP TABLE IF EXISTS users;
 \`;
 
 // Para criar o primeiro usuário, num seed fora da fatia:
@@ -1099,6 +1102,10 @@ export const sliceSchema = \`
     FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
     UNIQUE(provider, provider_user_id)
   );
+
+  -- down:
+  DROP TABLE IF EXISTS oauth_accounts;
+  DROP TABLE IF EXISTS users;
 \`;
 
 // ============================================================================
@@ -1366,6 +1373,9 @@ export const sliceSchema = \`
     enabled INTEGER DEFAULT 1,
     verified_at TIMESTAMP
   );
+
+  -- down:
+  DROP TABLE IF EXISTS ${names.table};
 \`;
 
 // ============================================================================

package/src/compiler/standalone-builder.ts

@@ -9,6 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { Err, Ok, type Result } from '../core/machine-types';
+import { SYNAPSE_VERSION } from '../version';
 import { type BuildReportEntry, buildAllClientBundles } from './client-bundler';
 import { resolveSlicesDir, type SlicesDirError } from './slice-discovery';
 
@@ -60,10 +61,23 @@ export async function buildStandalone(
   fs.mkdirSync(path.dirname(slicesDest), { recursive: true });
   fs.cpSync(slicesSrc, slicesDest, { recursive: true });
 
-  // 5. Copy package.json & tsconfig.json if present
+  // 5. Copy package.json & tsconfig.json if present (normalizing workspace:* dependencies)
   const pkgSrc = path.join(appRoot, 'package.json');
   if (fs.existsSync(pkgSrc)) {
-    fs.copyFileSync(pkgSrc, path.join(standaloneDir, 'package.json'));
+    try {
+      const rawPkg = fs.readFileSync(pkgSrc, 'utf-8');
+      const pkg = JSON.parse(rawPkg);
+      if (pkg.dependencies) {
+        for (const [dep, ver] of Object.entries(pkg.dependencies)) {
+          if (typeof ver === 'string' && ver.startsWith('workspace:')) {
+            pkg.dependencies[dep] = `^${SYNAPSE_VERSION}`;
+          }
+        }
+      }
+      fs.writeFileSync(path.join(standaloneDir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+    } catch {
+      fs.copyFileSync(pkgSrc, path.join(standaloneDir, 'package.json'));
+    }
   }
 
   const tsconfigSrc = path.join(appRoot, 'tsconfig.json');

package/src/core/action-context.ts

@@ -10,6 +10,7 @@ import { getEventHub } from '../runtime/event-hub';
 import type { DatabaseClient, QueryOptions, WhereCondition } from './database-client';
 import type { SessionContext } from './session-context';
 import { getStorage, type StorageClient } from './storage';
+import { declaredTopic, scopedTopic } from './topics';
 
 export interface StructuredLogger {
   info(message: string, context?: Record<string, unknown>): void;
@@ -31,6 +32,60 @@ export type EnqueueFn = <TPayload>(
 
 export type BroadcastFn = (topic: string, data: unknown) => number;
 
+export interface CookieOptions {
+  /**
+   * Defaults to true. A cookie written without stating otherwise is not readable by
+   * script; pass `false` explicitly to opt out.
+   */
+  httpOnly?: boolean;
+  /**
+   * Defaults to true. A cookie written without stating otherwise is not sent over
+   * plaintext; pass `false` explicitly to opt out.
+   */
+  secure?: boolean;
+  /**
+   * Defaults to `lax`. An explicit `strict` or `none` applies instead — the framework
+   * never infers a weaker policy from anything but a deliberate statement.
+   */
+  sameSite?: 'lax' | 'strict' | 'none';
+  maxAge?: number;
+  path?: string;
+  domain?: string;
+}
+
+export interface PendingCookie {
+  name: string;
+  value: string;
+  options?: CookieOptions;
+}
+
+/**
+ * Serializes one response cookie. The safe attributes are the **defaults**: a cookie
+ * written with no options at all is HttpOnly, Secure and SameSite=Lax, and only an
+ * explicit `false` (or a different `sameSite`) changes that. This is a breaking
+ * change from the previous opt-in behaviour.
+ */
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+  if (options.maxAge !== undefined) {
+    parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+  }
+  if (options.domain && !/[\r\n;\s]/.test(options.domain)) {
+    parts.push(`Domain=${options.domain.trim()}`);
+  }
+  const cleanPath = options.path && !/[\r\n;\s]/.test(options.path) ? options.path.trim() : '/';
+  parts.push(`Path=${cleanPath}`);
+  if (options.secure ?? true) {
+    parts.push('Secure');
+  }
+  if (options.httpOnly ?? true) {
+    parts.push('HttpOnly');
+  }
+  const sameSite = options.sameSite ?? 'lax';
+  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase() + sameSite.slice(1).toLowerCase()}`);
+  return parts.join('; ');
+}
+
 export interface ActionContext<TServices = Record<string, unknown>> extends DatabaseClient {
   /** Underlying Database Client */
   readonly db: DatabaseClient;
@@ -56,8 +111,14 @@ export interface ActionContext<TServices = Record<string, unknown>> extends Data
   /** Broadcasts a real-time event to SSE subscribers */
   readonly broadcast: BroadcastFn;
 
-  /** Lazy adapter for Kysely (if configured or requested) */
-  readonly kysely?: unknown;
+  /** Invalidates SSR cache entries by tag or completely */
+  readonly invalidateCache: (tags?: string[]) => void;
+
+  /** Sets an HTTP response cookie (e.g. HttpOnly session token) */
+  readonly setCookie: (name: string, value: string, options?: CookieOptions) => void;
+
+  /** Internal list of pending cookies to be set on the response */
+  readonly _pendingCookies?: PendingCookie[];
 }
 
 export function createDefaultLogger(sliceName?: string): StructuredLogger {
@@ -83,7 +144,12 @@ export interface ActionContextOptions<TServices = Record<string, unknown>> {
   enqueue?: EnqueueFn;
   storage?: StorageClient;
   broadcast?: BroadcastFn;
-  kysely?: unknown;
+  invalidateCache?: (tags?: string[]) => void;
+  /**
+   * The slice key (`<domain>/<name>`) this context belongs to. Publishing into a
+   * declared topic is only allowed for the declaration's owner.
+   */
+  sliceOwner?: string;
 }
 
 /**
@@ -101,10 +167,35 @@ export function createActionContext<TServices = Record<string, unknown>>(
     logger = createDefaultLogger(),
     enqueue = async () => 'job_noop',
     storage = getStorage(),
-    broadcast = (topic: string, data: unknown) => getEventHub().publish(topic, data),
-    kysely
+    invalidateCache = () => {},
+    sliceOwner
   } = options;
 
+  /**
+   * Publishing is declared, not inferred: the topic must exist in the session's
+   * tenant scope and this feature must be its declared owner. Anything else is
+   * rejected and notifies nobody.
+   */
+  const broadcast: BroadcastFn =
+    options.broadcast ??
+    ((topic: string, data: unknown) => {
+      const declaration = declaredTopic(topic, tenantId);
+
+      if (!declaration || (sliceOwner && declaration.owner !== sliceOwner)) {
+        logger.warn(
+          `Broadcast recusado no tópico "${topic}": não declarado${sliceOwner ? ` por ${sliceOwner}` : ''} (defineTopic).`
+        );
+        return 0;
+      }
+
+      return getEventHub().publish(scopedTopic(topic, tenantId), data);
+    });
+
+  const pendingCookies: PendingCookie[] = [];
+  const setCookie = (name: string, value: string, options?: CookieOptions) => {
+    pendingCookies.push({ name, value, options });
+  };
+
   const context: ActionContext<TServices> = {
     // ActionContext properties
     db,
@@ -115,7 +206,9 @@ export function createActionContext<TServices = Record<string, unknown>>(
     enqueue,
     storage,
     broadcast,
-    kysely,
+    invalidateCache,
+    setCookie,
+    _pendingCookies: pendingCookies,
 
     // DatabaseClient proxy methods
     query: <T = unknown>(sql: string, params?: unknown[]) => db.query<T>(sql, params),
@@ -139,8 +232,8 @@ export function createActionContext<TServices = Record<string, unknown>>(
           logger,
           enqueue,
           storage,
-          broadcast,
-          kysely: txDb
+          broadcast: options.broadcast,
+          sliceOwner
         });
         return operation(txContext);
       });

package/src/core/cache.ts

@@ -0,0 +1,139 @@
+/**
+ * SynapseJS - Incremental Static Regeneration (ISR) & SSR Micro-Cache Contract
+ *
+ * Slices export `sliceCache` or `cacheConfig` to declare caching boundaries,
+ * stale-while-revalidate windows, and tag-based invalidation.
+ */
+
+export interface SliceCacheConfig {
+  /** Time to live in seconds before the cached SSR HTML is considered stale */
+  ttlSeconds: number;
+  /** Stale-while-revalidate grace period in seconds */
+  staleWhileRevalidateSeconds?: number;
+  /** Invalidation tags (e.g. ['products', 'catalog']) */
+  tags?: string[];
+  /** Allowed query parameters to differentiate cache entries (default: all non-tracking parameters) */
+  allowedParams?: string[];
+}
+
+/**
+ * Declares SSR caching and ISR revalidation policy for a slice.
+ */
+export function defineCache(config: SliceCacheConfig): SliceCacheConfig {
+  return config;
+}
+
+const DEFAULT_TRACKING_PARAMS = new Set([
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_term',
+  'utm_content',
+  'fbclid',
+  'gclid',
+  'msclkid',
+  'mc_eid',
+  '_ga',
+  '_gl',
+  'ref',
+  'v'
+]);
+
+/**
+ * Normalizes a URL into a deterministic SSR cache key:
+ * - Strips common ad/tracking query parameters (utm_*, fbclid, etc.)
+ * - If allowedParams is specified, filters query parameters strictly to that allowlist
+ * - Sorts query parameters deterministically to avoid duplicate cache entries for different key orders
+ */
+export function normalizeCacheKey(url: URL, allowedParams?: string[]): string {
+  const pathname = url.pathname;
+  const searchParams = new URLSearchParams(url.search);
+
+  const cleanParams = new URLSearchParams();
+  const allowedSet = allowedParams ? new Set(allowedParams) : null;
+
+  const sortedKeys = Array.from(searchParams.keys()).sort();
+  for (const key of sortedKeys) {
+    if (allowedSet) {
+      if (allowedSet.has(key)) {
+        for (const val of searchParams.getAll(key)) {
+          cleanParams.append(key, val);
+        }
+      }
+    } else if (!DEFAULT_TRACKING_PARAMS.has(key.toLowerCase()) && !key.toLowerCase().startsWith('utm_')) {
+      for (const val of searchParams.getAll(key)) {
+        cleanParams.append(key, val);
+      }
+    }
+  }
+
+  const queryStr = cleanParams.toString();
+  return queryStr ? `${pathname}?${queryStr}` : pathname;
+}
+
+/**
+ * In-memory Bounded LRU Cache with O(1) get/set and automatic eviction of least recently used entries.
+ */
+export class BoundedLruCache<V> {
+  private map = new Map<string, V>();
+  readonly maxEntries: number;
+
+  constructor(maxEntries = 1000) {
+    this.maxEntries = Math.max(1, maxEntries);
+  }
+
+  get(key: string): V | undefined {
+    const val = this.map.get(key);
+    if (val !== undefined) {
+      // Re-insert to mark as most recently used (MRU)
+      this.map.delete(key);
+      this.map.set(key, val);
+    }
+    return val;
+  }
+
+  set(key: string, value: V): void {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxEntries) {
+      // Evict least recently used (first key in map iteration order)
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== undefined) {
+        this.map.delete(oldestKey);
+      }
+    }
+    this.map.set(key, value);
+  }
+
+  has(key: string): boolean {
+    return this.map.has(key);
+  }
+
+  delete(key: string): boolean {
+    return this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  entries(): IterableIterator<[string, V]> {
+    return this.map.entries();
+  }
+
+  values(): IterableIterator<V> {
+    return this.map.values();
+  }
+
+  keys(): IterableIterator<string> {
+    return this.map.keys();
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, V]> {
+    return this.map[Symbol.iterator]();
+  }
+}

package/src/core/config.ts

@@ -11,7 +11,7 @@ export interface SynapsePlugin {
   name: string;
   // biome-ignore lint/suspicious/noExplicitAny: generic boundary for framework server
   onBootstrap?: (server: any) => Promise<void> | void;
-  onRequest?: (req: Request) => Promise<Response | null | void> | Response | null | void;
+  onRequest?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
   onResponse?: (res: Response, req: Request) => Promise<Response> | Response;
   // biome-ignore lint/suspicious/noExplicitAny: generic boundary for database client
   onMigrate?: (db: any) => Promise<void> | void;
@@ -45,6 +45,107 @@ export interface SynapseConfig<TServices = Record<string, unknown>> {
    * Infrastructure lifecycle plugins (onBootstrap, onRequest, onResponse, onMigrate).
    */
   plugins?: SynapsePlugin[];
+
+  /**
+   * Compiler and client bundler configuration.
+   */
+  compiler?: {
+    vendorPackages?: string[];
+  };
+
+  /**
+   * Trust proxy headers (cf-connecting-ip, x-forwarded-for) for rate limiting and IP resolution.
+   * Opt-in: when this is not explicitly `true` (or SYNAPSE_TRUST_PROXY is not `true`), the
+   * immediate peer address is used and a rotating forwarding header cannot mint a new allowance.
+   */
+  trustProxy?: boolean;
+
+  /**
+   * Process-level maximum request body size, enforced by the HTTP server itself before any
+   * body reader runs (default: 12 MiB, above every per-route ceiling). It is the backstop
+   * behind the RPC (5 MiB), webhook (10 MiB) and upload (5 MiB) limits.
+   */
+  maxRequestBodyBytes?: number;
+
+  /**
+   * Rate limiting. Scope is the serving process only: each instance keeps its own counters,
+   * so N instances behind a load balancer permit N times the per-instance allowance.
+   */
+  rateLimit?: {
+    /** Maximum burst capacity (default: 150). */
+    capacity?: number;
+    /** Refill rate in tokens per second (default: 100). */
+    refillRate?: number;
+    /** Maximum tracked client identities before the registry is saturated (default: 10,000). */
+    maxBuckets?: number;
+  };
+
+  /**
+   * Max allowed payload bytes for RPC POST requests (default: 5MB).
+   */
+  maxRpcPayloadBytes?: number;
+
+  /**
+   * Max allowed payload bytes for Webhook POST requests (default: 10MB).
+   */
+  maxWebhookPayloadBytes?: number;
+
+  /**
+   * SSR Cache settings.
+   */
+  cache?: {
+    maxEntries?: number;
+  };
+
+  /**
+   * Third-party CDN and web-font origins (Tailwind's runtime compiler, Google Fonts).
+   * **Opt-in**: nothing third-party is referenced by default. When enabled, the
+   * content-security policy is rebuilt to permit exactly the configured origins, and
+   * the emitted tags carry a subresource-integrity hash — without one, the tag is not
+   * emitted at all, because an unpinned third-party script in an origin that holds a
+   * script-readable session cookie is the whole risk.
+   */
+  cdn?: {
+    enabled?: boolean;
+    /** SRI hash for the Tailwind runtime script (`sha384-...`). */
+    scriptIntegrity?: string;
+    /** SRI hash for the Google Fonts stylesheet (`sha384-...`). */
+    fontIntegrity?: string;
+  };
+
+  /**
+   * Realtime (event stream and WebSocket) limits. Long-lived connections consume a
+   * token from the rate limiter at most once, so these bounds — not the token bucket —
+   * are what caps concurrent streams.
+   */
+  realtime?: {
+    /** Maximum distinct topics with an open subscription (default: 1000). */
+    maxTopics?: number;
+    /** Maximum concurrently open realtime connections (default: 1000). */
+    maxSubscriptions?: number;
+    /** Maximum concurrently open realtime connections from one client (default: 8). */
+    maxConnectionsPerClient?: number;
+  };
+
+  /**
+   * Operator-supplied Content-Security-Policy. When present it is emitted as given —
+   * the framework never weakens it — and replaces the built-in policy.
+   */
+  contentSecurityPolicy?: string;
+
+  /**
+   * Image optimizer security settings.
+   * When `allowedDomains` is absent, any publicly routable host is permitted (loopback,
+   * link-local, private and metadata addresses are always refused) and the documentation
+   * says so rather than implying a restriction that is not enforced.
+   */
+  imageOptimizer?: {
+    allowedDomains?: string[];
+    /** Maximum bytes accepted from a remote image host (default: 10 MiB). */
+    maxResponseBytes?: number;
+    /** Maximum time a remote image fetch may take, in ms (default: 10,000). */
+    timeoutMs?: number;
+  };
 }
 
 export function defineConfig<TServices = Record<string, unknown>>(
@@ -57,20 +158,33 @@ const CONFIG_FILENAMES = ['synapse.config.ts', 'synapse.config.js', 'synapse.con
 
 /**
  * Discovers and loads `synapse.config.(ts|js|mjs)` from the application root.
+ *
+ * A configuration file that exists but cannot be loaded is **fatal**: the config
+ * carries security-relevant defaults (trusted proxy, body ceilings, realtime bounds),
+ * so degrading to an empty configuration silently would start the server with
+ * settings nobody chose. Absence of the file is not an error — it means "defaults".
  */
 export async function loadSynapseConfig(appDir: string): Promise<SynapseConfig> {
   for (const filename of CONFIG_FILENAMES) {
     const candidate = path.join(appDir, filename);
-    if (fs.existsSync(candidate)) {
-      try {
-        const mod = await import(candidate);
-        const config = mod.default || mod;
-        return typeof config === 'function' ? await config() : config;
-      } catch (err: unknown) {
-        const errMessage = err instanceof Error ? err.message : String(err);
-        console.warn(`[SynapseConfig] Aviso ao carregar ${filename}: ${errMessage}`);
-      }
+
+    if (!fs.existsSync(candidate)) {
+      continue;
     }
+
+    let mod: { default?: unknown } & Record<string, unknown>;
+
+    try {
+      mod = (await import(candidate)) as { default?: unknown } & Record<string, unknown>;
+    } catch (err: unknown) {
+      const errMessage = err instanceof Error ? err.message : String(err);
+
+      throw new Error(`[SynapseConfig] falha ao carregar ${filename}: ${errMessage}`);
+    }
+
+    const config = (mod.default || mod) as SynapseConfig | (() => SynapseConfig | Promise<SynapseConfig>);
+
+    return typeof config === 'function' ? await config() : config;
   }
 
   return {};