@ismaelsoilet/synapsejs 1.4.0 → 1.9.0

package/src/core/session-token.ts

@@ -17,27 +17,88 @@ import { Err, Ok, type Result } from './machine-types';
 export interface SessionClaims {
   userId: string;
   roles: string[];
+  tenantId?: string;
   /** Expiry, in seconds since the epoch. */
   exp: number;
 }
 
 export type SessionTokenError = 'INVALID_TOKEN' | 'EXPIRED_TOKEN' | 'TOKEN_REVOKED';
 
-const inMemoryRevokedSignatures = new Set<string>();
+/** Default bounds for the in-process revocation set. Both are configurable by env. */
+export const DEFAULT_REVOCATION_MAX_ENTRIES = 10_000;
+export const DEFAULT_REVOCATION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Insertion-ordered signature -> revocation instant. Bounded by cap and TTL. */
+const inMemoryRevokedSignatures = new Map<string, number>();
+
+function revocationMaxEntries(): number {
+  const raw = Number(process.env.SYNAPSE_REVOCATION_MAX_ENTRIES);
+
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_REVOCATION_MAX_ENTRIES;
+}
+
+function revocationTtlMs(): number {
+  const raw = Number(process.env.SYNAPSE_REVOCATION_TTL_MS);
+
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_REVOCATION_TTL_MS;
+}
+
+/**
+ * Drops expired entries and enforces the entry cap. Returns how many were pruned.
+ * Called on every write and read, so neither store grows without bound.
+ */
+export function pruneSessionTokenRevocations(now = Date.now()): number {
+  const ttl = revocationTtlMs();
+  let pruned = 0;
+
+  if (ttl > 0) {
+    for (const [signature, revokedAt] of inMemoryRevokedSignatures) {
+      if (now - revokedAt > ttl) {
+        inMemoryRevokedSignatures.delete(signature);
+        pruned++;
+      }
+    }
+  }
+
+  const cap = revocationMaxEntries();
+  while (inMemoryRevokedSignatures.size > cap) {
+    const oldest = inMemoryRevokedSignatures.keys().next().value;
+
+    if (oldest === undefined) {
+      break;
+    }
+
+    inMemoryRevokedSignatures.delete(oldest);
+    pruned++;
+  }
+
+  return pruned;
+}
 
 export function revokeSessionToken(token: string): boolean {
   const [, signature] = token.split('.');
   if (!signature) return false;
-  inMemoryRevokedSignatures.add(signature);
+  inMemoryRevokedSignatures.set(signature, Date.now());
+  pruneSessionTokenRevocations();
   return true;
 }
 
 export function isSessionTokenRevoked(token: string): boolean {
   const [, signature] = token.split('.');
   if (!signature) return true;
+
+  pruneSessionTokenRevocations();
+
   return inMemoryRevokedSignatures.has(signature);
 }
 
+/** Test/tooling helper: how many signatures the in-process set currently holds. */
+export function sessionTokenRevocationCount(): number {
+  pruneSessionTokenRevocations();
+
+  return inMemoryRevokedSignatures.size;
+}
+
 export function clearSessionTokenRevocations(): void {
   inMemoryRevokedSignatures.clear();
 }
@@ -52,24 +113,64 @@ export async function revokeSessionTokenInDb(db: DatabaseClient, token: string):
   await db.query(`
     CREATE TABLE IF NOT EXISTS _synapse_session_blacklist (
       token_signature TEXT PRIMARY KEY,
-      revoked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      revoked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      revoked_at_ms INTEGER
     );
   `);
 
+  try {
+    await db.query('ALTER TABLE _synapse_session_blacklist ADD COLUMN revoked_at_ms INTEGER;');
+  } catch {
+    // Column already present, or the engine refuses the ALTER: either way the
+    // table carries the revocation instant it needs for pruning.
+  }
+
+  const revokedAtMs = Date.now();
+
   await db
-    .query('INSERT INTO _synapse_session_blacklist (token_signature) VALUES ($1) ON CONFLICT DO NOTHING;', [signature])
+    .query(
+      'INSERT INTO _synapse_session_blacklist (token_signature, revoked_at_ms) VALUES ($1, $2) ON CONFLICT DO NOTHING;',
+      [signature, revokedAtMs]
+    )
     .catch(async () => {
       // SQLite fallback without ON CONFLICT DO NOTHING if needed
       await db
-        .query('INSERT OR IGNORE INTO _synapse_session_blacklist (token_signature) VALUES ($1);', [signature])
+        .query('INSERT OR IGNORE INTO _synapse_session_blacklist (token_signature, revoked_at_ms) VALUES ($1, $2);', [
+          signature,
+          revokedAtMs
+        ])
         .catch(() => {});
     });
 
   // Also sync in-memory for instant local lookup
-  inMemoryRevokedSignatures.add(signature);
+  inMemoryRevokedSignatures.set(signature, revokedAtMs);
+  pruneSessionTokenRevocations();
   return true;
 }
 
+/**
+ * Deletes persisted revocations older than the retention window. Returns how many
+ * rows were removed; SQLite and PostgreSQL both compare the epoch-millisecond
+ * column, so pruning does not depend on either dialect's date functions.
+ */
+export async function pruneSessionTokenRevocationsInDb(db: DatabaseClient, ttlMs = revocationTtlMs()): Promise<number> {
+  if (ttlMs <= 0) {
+    return 0;
+  }
+
+  try {
+    const cutoff = Date.now() - ttlMs;
+    const rows = await db.query<{ token_signature: string }>(
+      'DELETE FROM _synapse_session_blacklist WHERE revoked_at_ms IS NOT NULL AND revoked_at_ms < $1 RETURNING token_signature;',
+      [cutoff]
+    );
+
+    return Array.isArray(rows) ? rows.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * Checks whether a token signature exists in the database blacklist table.
  */
@@ -84,7 +185,8 @@ export async function isSessionTokenRevokedInDb(db: DatabaseClient, token: strin
       signature
     ]);
     if (rows && rows.length > 0) {
-      inMemoryRevokedSignatures.add(signature);
+      inMemoryRevokedSignatures.set(signature, Date.now());
+      pruneSessionTokenRevocations();
       return true;
     }
   } catch {
@@ -118,7 +220,7 @@ function constantTimeEquals(left: string, right: string): boolean {
 }
 
 export function signSessionToken(
-  claims: { userId: string; roles: string[] },
+  claims: { userId: string; roles: string[]; tenantId?: string },
   secret: string,
   maxAgeSeconds = 86_400
 ): string {
@@ -126,6 +228,7 @@ export function signSessionToken(
     JSON.stringify({
       userId: claims.userId,
       roles: claims.roles,
+      tenantId: claims.tenantId,
       exp: Math.floor(Date.now() / 1000) + maxAgeSeconds
     })
   );
@@ -162,6 +265,10 @@ export function verifySessionToken(
     return Err('INVALID_TOKEN');
   }
 
+  if (claims.tenantId !== undefined && typeof claims.tenantId !== 'string') {
+    return Err('INVALID_TOKEN');
+  }
+
   if (claims.exp * 1000 < Date.now()) {
     return Err('EXPIRED_TOKEN');
   }

package/src/core/sqlite-client.ts

@@ -38,6 +38,7 @@ export class SqliteDatabaseClient implements DatabaseClient {
   private statements: Map<string, Statement<unknown, SQLQueryBindings[]>> = new Map();
   private maxStatements: number;
   private txLock: Promise<void> = Promise.resolve();
+  private txDepth = 0;
 
   constructor(filePath?: string, maxStatements = 500) {
     this.maxStatements = maxStatements;
@@ -53,6 +54,11 @@ export class SqliteDatabaseClient implements DatabaseClient {
     }
 
     this.db.run('PRAGMA journal_mode = WAL;');
+    this.db.run('PRAGMA synchronous = NORMAL;');
+    this.db.run('PRAGMA busy_timeout = 5000;');
+    this.db.run('PRAGMA temp_store = MEMORY;');
+    this.db.run('PRAGMA cache_size = -64000;');
+    this.db.run('PRAGMA mmap_size = 268435456;');
     this.db.run('PRAGMA foreign_keys = ON;');
   }
 
@@ -161,6 +167,22 @@ export class SqliteDatabaseClient implements DatabaseClient {
   }
 
   async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
+    if (this.txDepth > 0) {
+      // Reentrant transaction: use SQLite SAVEPOINT
+      const spId = `sp_${++this.txDepth}`;
+      this.db.run(`SAVEPOINT ${spId};`);
+      try {
+        const result = await operation(this);
+        this.db.run(`RELEASE SAVEPOINT ${spId};`);
+        return result;
+      } catch (err) {
+        this.db.run(`ROLLBACK TO SAVEPOINT ${spId};`);
+        throw err;
+      } finally {
+        this.txDepth--;
+      }
+    }
+
     let releaseLock: () => void = () => {};
     const lockAcquired = new Promise<void>((resolve) => {
       releaseLock = resolve;
@@ -172,7 +194,8 @@ export class SqliteDatabaseClient implements DatabaseClient {
     await previousLock;
 
     try {
-      this.db.run('BEGIN TRANSACTION;');
+      this.txDepth = 1;
+      this.db.run('BEGIN IMMEDIATE TRANSACTION;');
       try {
         const result = await operation(this);
         this.db.run('COMMIT;');
@@ -180,6 +203,8 @@ export class SqliteDatabaseClient implements DatabaseClient {
       } catch (err) {
         this.db.run('ROLLBACK;');
         throw err;
+      } finally {
+        this.txDepth = 0;
       }
     } finally {
       releaseLock();

package/src/core/storage.ts

@@ -169,6 +169,43 @@ export class S3StorageAdapter implements StorageClient {
     return `${this.endpoint}/${cleanKey}`;
   }
 
+  /**
+   * Builds the SigV4 `Authorization` header for one request. Shared by every
+   * mutating operation — upload, delete — so no method reaches the service
+   * unauthenticated because its own signing was forgotten.
+   */
+  private buildAuthorization(
+    method: string,
+    url: URL,
+    headers: Record<string, string>,
+    payloadHash: string,
+    service = 's3'
+  ): string | null {
+    if (!this.accessKeyId || !this.secretAccessKey) {
+      return null;
+    }
+
+    const amzDate = headers['x-amz-date'];
+    const dateStamp = amzDate.slice(0, 8);
+    const sortedKeys = Object.keys(headers).sort();
+    const canonicalHeaders = sortedKeys.map((k) => `${k.toLowerCase()}:${headers[k].trim()}\n`).join('');
+    const signedHeaders = sortedKeys.map((k) => k.toLowerCase()).join(';');
+
+    const canonicalRequest = [method, url.pathname, '', canonicalHeaders, signedHeaders, payloadHash].join('\n');
+
+    const credentialScope = `${dateStamp}/${this.region}/${service}/aws4_request`;
+    const hashedCanonical = crypto.createHash('sha256').update(canonicalRequest).digest('hex');
+    const stringToSign = ['AWS4-HMAC-SHA256', amzDate, credentialScope, hashedCanonical].join('\n');
+
+    const kDate = crypto.createHmac('sha256', `AWS4${this.secretAccessKey}`).update(dateStamp).digest();
+    const kRegion = crypto.createHmac('sha256', kDate).update(this.region).digest();
+    const kService = crypto.createHmac('sha256', kRegion).update(service).digest();
+    const kSigning = crypto.createHmac('sha256', kService).update('aws4_request').digest();
+    const signature = crypto.createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+
+    return `AWS4-HMAC-SHA256 Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  }
+
   async upload(
     key: string,
     data: Uint8Array | ArrayBuffer | string,
@@ -181,7 +218,6 @@ export class S3StorageAdapter implements StorageClient {
 
     const now = new Date();
     const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
-    const dateStamp = amzDate.slice(0, 8);
     const contentSha256 = crypto.createHash('sha256').update(buffer).digest('hex');
 
     const headers: Record<string, string> = {
@@ -192,24 +228,10 @@ export class S3StorageAdapter implements StorageClient {
       host: url.host
     };
 
-    if (this.accessKeyId && this.secretAccessKey) {
-      const sortedKeys = Object.keys(headers).sort();
-      const canonicalHeaders = sortedKeys.map((k) => `${k.toLowerCase()}:${headers[k].trim()}\n`).join('');
-      const signedHeaders = sortedKeys.map((k) => k.toLowerCase()).join(';');
-
-      const canonicalRequest = ['PUT', url.pathname, '', canonicalHeaders, signedHeaders, contentSha256].join('\n');
-
-      const credentialScope = `${dateStamp}/${this.region}/s3/aws4_request`;
-      const hashedCanonical = crypto.createHash('sha256').update(canonicalRequest).digest('hex');
-      const stringToSign = ['AWS4-HMAC-SHA256', amzDate, credentialScope, hashedCanonical].join('\n');
+    const authorization = this.buildAuthorization('PUT', url, headers, contentSha256);
 
-      const kDate = crypto.createHmac('sha256', `AWS4${this.secretAccessKey}`).update(dateStamp).digest();
-      const kRegion = crypto.createHmac('sha256', kDate).update(this.region).digest();
-      const kService = crypto.createHmac('sha256', kRegion).update('s3').digest();
-      const kSigning = crypto.createHmac('sha256', kService).update('aws4_request').digest();
-      const signature = crypto.createHmac('sha256', kSigning).update(stringToSign).digest('hex');
-
-      headers.Authorization = `AWS4-HMAC-SHA256 Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    if (authorization) {
+      headers.Authorization = authorization;
     }
 
     const response = await fetch(targetUrl, {
@@ -219,11 +241,7 @@ export class S3StorageAdapter implements StorageClient {
     });
 
     if (!response.ok && response.status !== 200 && response.status !== 204) {
-      if (response.status === 403 || response.status === 404) {
-        // Fallback for mock/test environments
-      } else {
-        throw new Error(`Storage upload failed with HTTP status ${response.status}`);
-      }
+      throw new Error(`Storage upload failed with HTTP status ${response.status}`);
     }
 
     return {
@@ -285,7 +303,26 @@ export class S3StorageAdapter implements StorageClient {
     try {
       const cleanKey = sanitizeStorageKey(key);
       const targetUrl = this.getUrl(cleanKey);
-      const res = await fetch(targetUrl, { method: 'DELETE' });
+      const url = new URL(targetUrl);
+
+      // Signed with the same routine as upload(): an unauthenticated DELETE is
+      // either silently rejected by the service or, against a public-write bucket,
+      // an anonymous destructive request.
+      const headers: Record<string, string> = { host: url.host };
+      const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+      const payloadHash = crypto.createHash('sha256').update('').digest('hex');
+
+      headers['x-amz-content-sha256'] = payloadHash;
+      headers['x-amz-date'] = amzDate;
+
+      const authorization = this.buildAuthorization('DELETE', url, headers, payloadHash);
+
+      if (authorization) {
+        headers.Authorization = authorization;
+      }
+
+      const res = await fetch(targetUrl, { method: 'DELETE', headers });
+
       return res.status === 200 || res.status === 204;
     } catch {
       return false;

package/src/core/topics.ts

@@ -0,0 +1,84 @@
+/**
+ * SynapseJS - Declared Realtime Topics
+ *
+ * A topic is a name a slice deliberately declares together with who may read it and
+ * which feature may publish into it. Inferring authorization from a naming convention
+ * is not a security control, so the event-stream gateway refuses any topic that was
+ * never declared — a caller cannot subscribe to a name merely because it can spell it.
+ *
+ * Topics are namespaced by tenant: two tenants that use the same name are two
+ * independent topics that never observe each other's broadcasts.
+ */
+
+export interface TopicDeclaration {
+  /** The topic name as it appears in the URL. */
+  name: string;
+  /** The slice key (`<domain>/<name>`) permitted to publish into this topic. */
+  owner: string;
+  /** When set, the declaration exists only inside that tenant. */
+  tenantId?: string;
+  /** Roles permitted to subscribe. Empty means "any authenticated session". */
+  readRoles?: string[];
+  /** A deliberately public topic: reachable without a session. */
+  public?: boolean;
+}
+
+/**
+ * The complete set of realtime rejection codes and the status each is returned with.
+ * Both transports draw from this table and the machine contract enumerates it, so a
+ * code cannot be invented at a refusal site.
+ */
+export const REALTIME_REJECTIONS = {
+  UNAUTHENTICATED: 401,
+  TOPIC_NOT_FOUND: 404,
+  TOPIC_FORBIDDEN: 403,
+  RATE_LIMIT_EXCEEDED: 429,
+  REALTIME_LIMIT_EXCEEDED: 429,
+  ORIGIN_NOT_ALLOWED: 403
+} as const;
+
+export type RealtimeRejectionCode = keyof typeof REALTIME_REJECTIONS;
+
+const registry = new Map<string, TopicDeclaration>();
+
+function registryKey(name: string, tenantId?: string): string {
+  return `${tenantId ?? '*'}:${name}`;
+}
+
+/**
+ * Declares a topic. Call it at module scope in the slice that owns the topic.
+ */
+export function defineTopic(declaration: TopicDeclaration): TopicDeclaration {
+  registry.set(registryKey(declaration.name, declaration.tenantId), declaration);
+
+  return declaration;
+}
+
+/**
+ * The declaration that governs `name` for a session in `tenantId`: an exact
+ * tenant-scoped declaration wins over a global one. A name declared only for another
+ * tenant resolves to nothing here, so the refusal cannot disclose that it exists.
+ */
+export function declaredTopic(name: string, tenantId?: string): TopicDeclaration | undefined {
+  const scoped = registry.get(registryKey(name, tenantId));
+
+  if (scoped) {
+    return scoped;
+  }
+
+  return registry.get(registryKey(name));
+}
+
+export function declaredTopics(): TopicDeclaration[] {
+  return Array.from(registry.values());
+}
+
+/** The effective, tenant-scoped hub key for a topic. */
+export function scopedTopic(name: string, tenantId?: string): string {
+  return `${tenantId || 'global'}:${name}`;
+}
+
+/** Test helper: drops every declaration. */
+export function resetDeclaredTopics(): void {
+  registry.clear();
+}

package/src/core/webhook-signature.ts

@@ -0,0 +1,151 @@
+/**
+ * SynapseJS - Webhook Signature Verification
+ *
+ * A webhook endpoint is a public write surface, so the framework ships the two
+ * primitives a receiver needs to treat it as one: a constant-time comparison of the
+ * provider's signature over the raw body, and a bounded replay window so a captured
+ * delivery cannot be replayed. Verifying a signature is not enough on its own — a
+ * valid signature stays valid forever unless the receiver also tracks what it has
+ * already accepted.
+ */
+
+import * as crypto from 'crypto';
+import { Err, Ok, type Result } from './machine-types';
+
+export type WebhookSignatureError = 'INVALID_SIGNATURE' | 'TIMESTAMP_OUT_OF_WINDOW' | 'REPLAYED_DELIVERY';
+
+/** Compares two strings without leaking their difference through timing. */
+export function constantTimeEquals(left: string, right: string): boolean {
+  const a = Buffer.from(left, 'utf-8');
+  const b = Buffer.from(right, 'utf-8');
+
+  if (a.length !== b.length) {
+    // Still perform a comparison of equal length so the failure is not timing-visible.
+    const padded = Buffer.alloc(a.length);
+    crypto.timingSafeEqual(a, padded);
+
+    return false;
+  }
+
+  return crypto.timingSafeEqual(a, b);
+}
+
+/** The canonical signed value: `<timestamp>.<raw body>`. */
+export function signedPayload(timestampSeconds: number, payload: Uint8Array): Buffer {
+  return Buffer.concat([Buffer.from(`${timestampSeconds}.`, 'utf-8'), Buffer.from(payload)]);
+}
+
+/** HMAC-SHA256 of `<timestamp>.<body>`, hex encoded — the shape providers send. */
+export function signWebhookPayload(secret: string, timestampSeconds: number, payload: Uint8Array): string {
+  return crypto.createHmac('sha256', secret).update(signedPayload(timestampSeconds, payload)).digest('hex');
+}
+
+export interface VerifyWebhookOptions {
+  /** The raw request body, byte for byte — a re-serialized JSON body will not verify. */
+  payload: Uint8Array;
+  /** The signature the provider sent (hex, `sha256=...` accepted). */
+  signature: string;
+  secret: string;
+  /** The provider's delivery timestamp, in seconds. */
+  timestamp: number;
+  /** How far from now a delivery may be, in seconds (default: 300). */
+  toleranceSeconds?: number;
+  /** Injected for tests. */
+  nowSeconds?: number;
+}
+
+/**
+ * Verifies the signature and the delivery window. A signature that matches but whose
+ * timestamp is outside the tolerance is refused: otherwise a captured delivery stays
+ * valid forever.
+ */
+export function verifyWebhookSignature(options: VerifyWebhookOptions): Result<true, WebhookSignatureError> {
+  const tolerance = options.toleranceSeconds ?? 300;
+  const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const provided = options.signature.replace(/^sha256=/i, '').trim();
+
+  if (!Number.isFinite(options.timestamp) || Math.abs(now - options.timestamp) > tolerance) {
+    return Err('TIMESTAMP_OUT_OF_WINDOW');
+  }
+
+  const expected = signWebhookPayload(options.secret, options.timestamp, options.payload);
+
+  return constantTimeEquals(expected, provided) ? Ok(true) : Err('INVALID_SIGNATURE');
+}
+
+export interface ReplayGuardOptions {
+  /** How long a signature stays in the window, in seconds (default: 300). */
+  ttlSeconds?: number;
+  /** Maximum tracked signatures (default: 10,000). */
+  maxEntries?: number;
+}
+
+/**
+ * Remembers which signatures have already been accepted, bounded by a time-to-live
+ * and an entry cap so a flood of deliveries cannot grow the store without bound.
+ */
+export class WebhookReplayGuard {
+  private readonly ttlSeconds: number;
+  private readonly maxEntries: number;
+  private accepted = new Map<string, number>();
+
+  constructor(options: ReplayGuardOptions = {}) {
+    this.ttlSeconds = options.ttlSeconds ?? 300;
+    this.maxEntries = options.maxEntries ?? 10_000;
+  }
+
+  /** True when this signature has not been accepted inside the window. */
+  isFresh(signature: string, nowSeconds?: number): boolean {
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    this.prune(now);
+
+    return !this.accepted.has(signature);
+  }
+
+  /** Records a signature as accepted. Returns false when it was already inside the window. */
+  accept(signature: string, nowSeconds?: number): boolean {
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    this.prune(now);
+
+    if (this.accepted.has(signature)) {
+      return false;
+    }
+
+    while (this.accepted.size >= this.maxEntries) {
+      const oldest = this.accepted.keys().next().value;
+
+      if (oldest === undefined) {
+        break;
+      }
+
+      this.accepted.delete(oldest);
+    }
+
+    this.accepted.set(signature, now);
+
+    return true;
+  }
+
+  /** Drops entries older than the window. Returns how many were removed. */
+  prune(nowSeconds?: number): number {
+    const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+    let pruned = 0;
+
+    for (const [signature, acceptedAt] of this.accepted) {
+      if (now - acceptedAt > this.ttlSeconds) {
+        this.accepted.delete(signature);
+        pruned++;
+      }
+    }
+
+    return pruned;
+  }
+
+  get size(): number {
+    return this.accepted.size;
+  }
+
+  clear(): void {
+    this.accepted.clear();
+  }
+}

package/src/core/websocket.ts

@@ -0,0 +1,30 @@
+/**
+ * SynapseJS - Native Bidirectional WebSocket Abstraction
+ *
+ * Provides a type-safe contract for real-time duplex communication
+ * seamlessly integrated with native Bun.serve WebSockets.
+ */
+
+export interface SynapseWebSocket<TServerMsg = unknown> {
+  readonly id: string;
+  readonly sliceKey: string;
+  send(message: TServerMsg | string): void;
+  close(code?: number, reason?: string): void;
+  data: Record<string, unknown>;
+}
+
+export interface SliceSocketDefinition<TClientMsg = unknown, TServerMsg = unknown> {
+  onOpen?: (ws: SynapseWebSocket<TServerMsg>) => void | Promise<void>;
+  onMessage: (ws: SynapseWebSocket<TServerMsg>, message: TClientMsg) => void | Promise<void>;
+  onClose?: (ws: SynapseWebSocket<TServerMsg>, code: number, reason: string) => void | Promise<void>;
+}
+
+/**
+ * Declares a bidirectional WebSocket endpoint for a slice.
+ * Automatically discovered and mounted at `GET /_synapse/ws/:domain/:name`.
+ */
+export function defineSocket<TClientMsg = unknown, TServerMsg = unknown>(
+  def: SliceSocketDefinition<TClientMsg, TServerMsg>
+): SliceSocketDefinition<TClientMsg, TServerMsg> {
+  return def;
+}

package/src/index.ts

@@ -65,7 +65,13 @@ export {
   parseOracleJunit,
   runSliceOracles
 } from './compiler/oracle-runner';
-export { type ScaffoldError, type ScaffoldErrorCode, scaffoldCrud, scaffoldSlice } from './compiler/scaffolder';
+export {
+  type ScaffoldError,
+  type ScaffoldErrorCode,
+  scaffoldCrud,
+  scaffoldShared,
+  scaffoldSlice
+} from './compiler/scaffolder';
 export { orderSlicesByDag, parseTableDependencies } from './compiler/schema-dag';
 export {
   checkSchemaDrift,
@@ -128,6 +134,8 @@ export {
   type SliceLoadError,
   type SliceLoaderContext,
   type SliceMetadata,
-  SynapseServer
+  SynapseServer,
+  type WebhookEvent
 } from './runtime/server';
+export { SYNAPSE_VERSION } from './version';
 export { fc };