dzql 0.6.37 → 0.8.0

package/src/cli/compiler/permissions.ts

@@ -1,43 +1,43 @@
 /**
- * Compiles a permission rule into SQL.
+ * Compiles permission rules into SQL.
  *
  * Supported formats:
- * - Literal: TRUE, FALSE
+ * - Literal: TRUE (public), FALSE (nobody), AUTHENTICATED (any signed-in user)
  * - Simple field check: @author_id (implies author_id == user_id)
  * - Explicit comparison: @field == @user_id
  * - Single-hop traversal: @org_id->acts_for[org_id=$]{active}.user_id
  * - Multi-hop traversal: @venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id
- * - Deep traversal: @site_id->sites.venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id
+ * - Filtered middle hop: @occasion_id->occasion_promoters[occasion_id=$].promoter_id->user_orgs[org_id=$].user_id
+ * - Several filters: @org_id->user_orgs[org_id=$,role=owner].user_id
  * - Table-first: contractor_rights[package_id=@package_id]{active}.contractor_org_id->...
  *
- * Uses the shared path parser for parity with notification compilation.
- *
- * @param entityName - The entity name
- * @param rule - The permission rule string
- * @param context - Optional context (unused)
- * @param dataVar - Either a JSONB variable name (e.g., 'p_data') or a table name (e.g., 'packages')
- *                  When it's a table name, we use table.column syntax instead of jsonb->>'column'
+ * Uses the shared path parser for parity with notification and subscribe compilation.
+ * A rule that can't be compiled throws PathCompileError; it never compiles to FALSE.
  */
 
-import { parsePath, compilePathToExists } from "./paths.js";
-
-export function compilePermission(entityName: string, rule: string, context: any, dataVar: string = 'p_data'): string {
-  // Literal TRUE/FALSE - public access or deny all
-  if (rule === 'TRUE' || rule === 'true') {
-    return 'TRUE';
-  }
-  if (rule === 'FALSE' || rule === 'false') {
-    return 'FALSE';
-  }
+import { parsePath, compilePathToExists, PathCompileError, type RowSource } from "./paths.js";
 
-  // Parse the path
+/**
+ * @param entityName - The entity name (for error messages)
+ * @param rule - The permission rule string
+ * @param context - Optional context (unused)
+ * @param dataVar - A JSONB variable name (e.g., 'p_data', 'v_old_data'), a table name or
+ *                  alias in scope (e.g., 'packages'), or an explicit RowSource
+ */
+export function compilePermission(entityName: string, rule: string, context: any, dataVar: string | RowSource = 'p_data'): string {
   const parsed = parsePath(rule);
-
   if (!parsed.isValid) {
-    console.warn(`[Compiler] Warning: ${parsed.error}`);
-    return 'FALSE';
+    throw new PathCompileError(`${entityName}: ${parsed.error}`, rule);
   }
-
-  // Compile to EXISTS check
   return compilePathToExists(parsed, dataVar, 'p_user_id');
 }
+
+/**
+ * Compile a list of rules: any one of them grants access. An empty or missing
+ * list denies everyone.
+ */
+export function compileRuleList(entityName: string, rules: string[] | undefined, dataVar: string | RowSource = 'p_data'): string {
+  if (!rules || rules.length === 0) return 'FALSE';
+  if (rules.length === 1) return compilePermission(entityName, rules[0], null, dataVar);
+  return rules.map(rule => `(${compilePermission(entityName, rule, null, dataVar)})`).join(' OR ');
+}

package/src/cli/index.ts

@@ -1,9 +1,6 @@
 #!/usr/bin/env bun
 import { loadDomain } from "./compiler/loader.js";
-import { analyzeDomain } from "./compiler/analyzer.js";
-import { generateIR } from "./compiler/ir.js";
-import { generateCoreSQL, generateAuthSQL, generateEntitySQL, generateSchemaSQL } from "./codegen/sql.js";
-import { generateSubscribableSQL, generateComputeAffectedKeysFunction } from "./codegen/subscribable_sql.js";
+import { compileDomain, DomainValidationError } from "./compile.js";
 import { generateManifest } from "./codegen/manifest.js";
 import { generateSubscribableStore } from "./codegen/subscribable_store.js";
 import { generateClientSDK } from "./codegen/client.js";
@@ -60,62 +57,19 @@ async function main() {
       const domain = await loadDomain(fullInputPath);
       console.log("[Compiler] Domain loaded.");
 
-      const errors = analyzeDomain(domain);
-      if (errors.length > 0) {
-        console.error("[Compiler] Validation Failed:");
-        errors.forEach(err => console.error(`  - ${err}`));
-        process.exit(1);
-      }
-
-      // Phase 2: Generate IR
-      const ir = generateIR(domain);
-      console.log(`[Compiler] IR Generated. Subscribables: ${Object.keys(ir.subscribables).join(', ')}`);
-
-      // Phase 3: Generate SQL
-      const coreSQL = generateCoreSQL();
-
-      // Topologically sort entities by FK dependencies
-      // Entities must be created before entities that reference them
-      // Also detects circular FKs that need deferred constraint creation
-      const { sorted: sortedEntityNames, circularFKs } = topologicalSortEntities(ir.entities);
-
-      // Build set of circular FK columns for stripping during schema generation
-      const circularFKSet = new Set(circularFKs.map(fk => `${fk.table}.${fk.column}`));
-
-      const entitySQL: string[] = [];
-      for (const name of sortedEntityNames) {
-        const entityIR = ir.entities[name];
-        // Pass circular FK info so schema generation can strip those constraints
-        entitySQL.push(generateSchemaSQL(name, entityIR, circularFKSet));
-        // Skip CRUD generation for unmanaged entities (e.g., junction tables)
-        if (entityIR.managed !== false) {
-          entitySQL.push(generateEntitySQL(name, entityIR));
-        } else {
-          console.log(`[Compiler] Skipping CRUD for unmanaged entity: ${name}`);
+      let compiled;
+      try {
+        compiled = compileDomain(domain);
+      } catch (e) {
+        if (e instanceof DomainValidationError) {
+          console.error("[Compiler] Validation Failed:");
+          e.errors.forEach(err => console.error(`  - ${err}`));
+          process.exit(1);
         }
+        throw e;
       }
-
-      // Add deferred FK constraints at the end (for circular dependencies)
-      if (circularFKs.length > 0) {
-        entitySQL.push(generateDeferredFKConstraints(circularFKs));
-      }
-
-      // Generate subscribable SQL functions
-      const subscribableSQL: string[] = [];
-      const subscribableNames = Object.keys(ir.subscribables);
-      for (const [name, subIR] of Object.entries(ir.subscribables)) {
-        console.log(`[Compiler] Generating SQL for subscribable: ${name}`);
-        subscribableSQL.push(generateSubscribableSQL(name, subIR as any, ir.entities));
-      }
-      // Generate central compute_affected_keys function that aggregates all subscribables
-      subscribableSQL.push(generateComputeAffectedKeysFunction(subscribableNames));
-
-      // Collect custom functions SQL
-      const customFunctionSQL: string[] = [];
-      for (const fn of ir.customFunctions) {
-        console.log(`[Compiler] Adding custom function: ${fn.name}`);
-        customFunctionSQL.push(fn.sql);
-      }
+      const { ir, coreSQL, schemaSQL } = compiled;
+      console.log(`[Compiler] IR Generated. Subscribables: ${Object.keys(ir.subscribables).join(', ')}`);
 
       // Phase 4: Generate Manifest
       const manifest = generateManifest(ir);
@@ -128,26 +82,15 @@ async function main() {
 
       writeFileSync(resolve(dbDir, `000_core.sql`), coreSQL);
       const timestamp = new Date().toISOString().replace(/[:.-]/g, '');
+      writeFileSync(resolve(dbDir, `${timestamp}_schema.sql`), schemaSQL);
 
-      // Combine entity SQL with auth functions and custom functions
-      // Auth functions must come after schema (they depend on users table)
-      const authSQL = generateAuthSQL();
-      let schemaContent = entitySQL.join('\n');
-      schemaContent += '\n\n-- Auth Functions\n' + authSQL;
-      if (customFunctionSQL.length > 0) {
-        schemaContent += '\n\n-- Custom Functions\n' + customFunctionSQL.join('\n\n');
-      }
-      writeFileSync(resolve(dbDir, `${timestamp}_schema.sql`), schemaContent);
-
-      if (customFunctionSQL.length > 0) {
-        console.log(`[Generated] ${customFunctionSQL.length} Custom Functions`);
+      if (compiled.customFunctionCount > 0) {
+        console.log(`[Generated] ${compiled.customFunctionCount} Custom Functions`);
       }
 
       // Write subscribable SQL
-      if (subscribableSQL.length > 0) {
-        writeFileSync(resolve(dbDir, `${timestamp}_subscribables.sql`), subscribableSQL.join('\n\n'));
-        console.log(`[Generated] ${subscribableSQL.length} Subscribable SQL functions`);
-      }
+      writeFileSync(resolve(dbDir, `${timestamp}_subscribables.sql`), compiled.subscribableSQL);
+      console.log(`[Generated] Subscribable SQL for ${Object.keys(ir.subscribables).length} subscribables`);
 
       console.log(`[Generated] DB Migrations in ${dbDir}`);
 
@@ -227,148 +170,3 @@ async function main() {
 }
 
 main();
-
-/** FK info for dependency analysis */
-interface FKInfo {
-  table: string;
-  column: string;
-  referencedTable: string;
-  fullConstraint: string; // e.g., "int NOT NULL REFERENCES users(id)"
-}
-
-/** Result of topological sort with cycle detection */
-interface SortResult {
-  sorted: string[];
-  circularFKs: FKInfo[];
-}
-
-/**
- * Topologically sort entities based on FK dependencies.
- * Entities that are referenced by others come first.
- * Uses Kahn's algorithm for topological sorting.
- * Returns both sorted order and any circular FK constraints that need deferred creation.
- */
-function topologicalSortEntities(entities: Record<string, any>): SortResult {
-  const entityNames = Object.keys(entities);
-
-  // Build dependency graph: entity -> entities it depends on (references)
-  const dependencies: Record<string, Set<string>> = {};
-  const dependents: Record<string, Set<string>> = {};
-
-  // Track all FK info for cycle detection
-  const allFKs: FKInfo[] = [];
-
-  for (const name of entityNames) {
-    dependencies[name] = new Set();
-    dependents[name] = new Set();
-  }
-
-  // Parse REFERENCES from column types
-  for (const name of entityNames) {
-    const entity = entities[name];
-    for (const col of entity.columns || []) {
-      const match = col.type?.match(/REFERENCES\s+(\w+)/i);
-      if (match) {
-        const referencedEntity = match[1];
-        // Only track dependencies to entities we're managing
-        if (entityNames.includes(referencedEntity)) {
-          dependencies[name].add(referencedEntity);
-          dependents[referencedEntity].add(name);
-          allFKs.push({
-            table: name,
-            column: col.name,
-            referencedTable: referencedEntity,
-            fullConstraint: col.type
-          });
-        }
-      }
-    }
-  }
-
-  // Kahn's algorithm
-  const result: string[] = [];
-  const noIncoming: string[] = [];
-  const remainingDeps: Record<string, Set<string>> = {};
-
-  // Copy dependencies for mutation
-  for (const name of entityNames) {
-    remainingDeps[name] = new Set(dependencies[name]);
-  }
-
-  // Find entities with no dependencies (no incoming edges)
-  for (const name of entityNames) {
-    if (remainingDeps[name].size === 0) {
-      noIncoming.push(name);
-    }
-  }
-
-  while (noIncoming.length > 0) {
-    const node = noIncoming.shift()!;
-    result.push(node);
-
-    // Remove this node from the graph
-    for (const dependent of dependents[node]) {
-      remainingDeps[dependent].delete(node);
-      if (remainingDeps[dependent].size === 0) {
-        noIncoming.push(dependent);
-      }
-    }
-  }
-
-  // Detect circular FKs
-  const circularFKs: FKInfo[] = [];
-  if (result.length !== entityNames.length) {
-    const cycleEntities = new Set(entityNames.filter(n => !result.includes(n)));
-    console.warn(`[Compiler] Warning: Circular FK dependencies detected among: ${[...cycleEntities].join(', ')}`);
-
-    // Find FKs that are part of the cycle - these need deferred creation
-    for (const fk of allFKs) {
-      if (cycleEntities.has(fk.table) && cycleEntities.has(fk.referencedTable)) {
-        circularFKs.push(fk);
-        console.log(`[Compiler] Deferring circular FK: ${fk.table}.${fk.column} -> ${fk.referencedTable}`);
-      }
-    }
-
-    // Add remaining entities (cycle members) to result
-    result.push(...cycleEntities);
-  }
-
-  return { sorted: result, circularFKs };
-}
-
-/**
- * Generate ALTER TABLE statements for deferred circular FK constraints.
- */
-function generateDeferredFKConstraints(circularFKs: FKInfo[]): string {
-  if (circularFKs.length === 0) return '';
-
-  const statements: string[] = [
-    '\n-- === DEFERRED FK CONSTRAINTS (for circular dependencies) ===\n'
-  ];
-
-  for (const fk of circularFKs) {
-    // Extract the REFERENCES part from the full constraint
-    const refMatch = fk.fullConstraint.match(/REFERENCES\s+(\w+)(\([^)]+\))?(\s+ON\s+.+)?/i);
-    if (refMatch) {
-      const targetTable = refMatch[1];
-      const targetCol = refMatch[2] || '(id)';
-      const cascadeClause = refMatch[3] || '';
-      const constraintName = `fk_${fk.table}_${fk.column}`;
-
-      statements.push(`ALTER TABLE ${fk.table} ADD CONSTRAINT ${constraintName} FOREIGN KEY (${fk.column}) REFERENCES ${targetTable}${targetCol}${cascadeClause};`);
-    }
-  }
-
-  return statements.join('\n');
-}
-
-/**
- * Remove REFERENCES clause from a column type for deferred FK creation.
- * Preserves NOT NULL and other modifiers.
- */
-function stripReferences(columnType: string): string {
-  // Remove REFERENCES clause and any ON DELETE/UPDATE clauses
-  return columnType
-    .replace(/\s*REFERENCES\s+\w+(\([^)]+\))?(\s+ON\s+(DELETE|UPDATE)\s+(CASCADE|SET NULL|SET DEFAULT|RESTRICT|NO ACTION))*\s*/gi, ' ')
-    .trim();
-}

package/src/client/ws.ts

@@ -51,6 +51,8 @@ export class WebSocketManager {
   protected maxReconnectAttempts = 5;
   protected tokenName = 'dzql_token';
   protected isShuttingDown = false;
+  /** The URL last given to connect(): a reconnect goes back to it. */
+  protected url: string | null = null;
 
   public user: any = null;
   public ready: boolean = false;
@@ -101,15 +103,16 @@ export class WebSocketManager {
     this.ready = false;
     this.ws?.close();
     this.ws = null;
-    this.isShuttingDown = false;
   }
 
   connect(url: string | null = null, timeout = 5000): Promise<void> {
     return new Promise((resolve, reject) => {
       this.ready = false;
       this.user = null;
+      this.isShuttingDown = false;
 
-      let wsUrl = url;
+      let wsUrl = url ?? this.url;
+      if (url) this.url = url;
       if (!wsUrl) {
         if (typeof globalThis !== "undefined" && "window" in globalThis) {
           const win = globalThis as unknown as { location: { protocol: string; host: string } };
@@ -128,19 +131,20 @@ export class WebSocketManager {
       }
 
       const connectionTimeout = setTimeout(() => {
-        this.ws?.close();
+        socket.close();
         reject(new Error('WebSocket connection timed out'));
       }, timeout);
 
-      this.ws = new WebSocket(wsUrl);
+      const socket = new WebSocket(wsUrl);
+      this.ws = socket;
 
-      this.ws.onopen = () => {
+      socket.onopen = () => {
         clearTimeout(connectionTimeout);
         this.reconnectAttempts = 0;
         resolve();
       };
 
-      this.ws.onmessage = (event) => {
+      socket.onmessage = (event) => {
         try {
           this.handleMessage(JSON.parse(event.data));
         } catch (error) {
@@ -148,13 +152,14 @@ export class WebSocketManager {
         }
       };
 
-      this.ws.onclose = () => {
-        if (!this.isShuttingDown) {
+      // only the current socket reconnects: one replaced by a later connect() or a disconnect() does not
+      socket.onclose = () => {
+        if (this.ws === socket && !this.isShuttingDown) {
           this.attemptReconnect();
         }
       };
 
-      this.ws.onerror = (error) => {
+      socket.onerror = (error) => {
         clearTimeout(connectionTimeout);
         reject(error);
       };
@@ -164,7 +169,12 @@ export class WebSocketManager {
   attemptReconnect() {
     if (this.reconnectAttempts < this.maxReconnectAttempts) {
       this.reconnectAttempts++;
-      setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
+      setTimeout(() => {
+        // a disconnect() since, or a connect() already open or opening, needs no reconnect
+        if (this.isShuttingDown || (this.ws && this.ws.readyState <= WebSocket.OPEN)) return;
+        // a failed attempt closes, and its onclose tries again: nothing to reject to
+        this.connect().catch(() => {});
+      }, 1000 * this.reconnectAttempts);
     }
   }
 

package/src/postgres/auth-jwt-sql.ts

@@ -0,0 +1,32 @@
+/**
+ * Auth-JWT SQL helpers — pure filesystem access, no jose dependency.
+ *
+ * These are split out of `auth-jwt.ts` so the `delta init` CLI (which only
+ * needs the file path) can run in projects that haven't installed jose.
+ * Consumers of the `@blueshed/delta/auth-jwt` subpath still get these via
+ * re-export from `auth-jwt.ts`.
+ */
+import type { Pool } from "pg";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const AUTH_JWT_SQL_PATH = join(import.meta.dir, "..", "sql", "auth-jwt.sql");
+
+/** Absolute path to the reference auth-jwt SQL file (users + register + login). */
+export function authJwtSqlFile(): string {
+  return AUTH_JWT_SQL_PATH;
+}
+
+/** The reference auth-jwt SQL as a string. */
+export function authJwtSql(): string {
+  return readFileSync(AUTH_JWT_SQL_PATH, "utf8");
+}
+
+/**
+ * Apply the reference users schema + login/register stored functions to a
+ * pool. Idempotent. Call once at boot alongside `applyFramework(pool)`, or
+ * use `delta init --with-auth` to copy the file for docker-entrypoint use.
+ */
+export async function applyAuthJwtSchema(pool: Pool): Promise<void> {
+  await pool.query(authJwtSql());
+}

package/src/postgres/auth-jwt.ts

@@ -0,0 +1,209 @@
+/**
+ * Auth-JWT — reference `DeltaAuth` implementation using JWTs (jose) and
+ * Postgres stored functions for credential verification.
+ *
+ * Ship this as an opt-in subpath: `@blueshed/delta/auth-jwt`. Users who want
+ * a different auth scheme (sessions, OAuth, magic links, none) implement
+ * their own `DeltaAuth` instead.
+ *
+ * Contract with Postgres:
+ *   - `login(email, password) RETURNS jsonb` — return a user row or NULL.
+ *   - `register(name, email, password) RETURNS jsonb` — return a user row,
+ *     raise unique_violation (23505) on duplicate email.
+ *
+ * Both are overridable via the `loginSql` / `registerSql` options.
+ *
+ *   import { jwtAuth } from "@blueshed/delta/auth-jwt";
+ *
+ *   const auth = jwtAuth({
+ *     pool,
+ *     secret: process.env.JWT_SECRET!,
+ *   });
+ *
+ *   wireAuth(ws, auth);
+ *   await createDocListener(ws, pool, { auth });
+ *
+ * SQL-file helpers (`authJwtSqlFile`, `authJwtSql`, `applyAuthJwtSchema`) live
+ * in `./auth-jwt-sql.ts` and are re-exported from here for convenience. They
+ * have no jose dependency, so the `delta init` CLI can load them without
+ * forcing consumers to install jose just to copy SQL files.
+ */
+import { SignJWT, jwtVerify, decodeJwt } from "jose";
+import type { Pool } from "pg";
+import { createLogger } from "@blueshed/delta/logger";
+import type { DeltaAuth } from "@blueshed/delta/auth";
+import { dropClientSubscriptions } from "@blueshed/delta/backend";
+
+/** Algorithm this module signs with — pinned on verify to prevent alg-confusion. */
+const JWT_ALG = "HS256";
+
+export {
+  authJwtSqlFile,
+  authJwtSql,
+  applyAuthJwtSchema,
+} from "./auth-jwt-sql";
+
+const log = createLogger("[auth-jwt]");
+
+export interface User {
+  id: number | string;
+  name?: string;
+  email?: string;
+  [key: string]: unknown;
+}
+
+export interface JwtAuthOpts {
+  pool: Pool;
+  secret: string | Uint8Array;
+  expirationTime?: string;
+  loginSql?: string;
+  registerSql?: string;
+  /**
+   * Optional re-validation hook for `authenticate`. A JWT is stateless: by
+   * default a signed, unexpired token grants access even if the user was
+   * since deleted or disabled (the documented trade-off of stateless auth).
+   * Provide `verifyUser` to re-check the identity against the database on
+   * each `authenticate`; return the (possibly refreshed) user to allow, or
+   * `null` to reject. Not called on `login` / `register` (those just hit the DB).
+   */
+  verifyUser?: (user: User, pool: Pool) => Promise<User | null>;
+}
+
+/** Set the socket's identity, tearing down a prior *different* identity's
+ *  live subscriptions so an identity switch on one socket can't keep
+ *  receiving the previous user's scoped docs. `expires` is when the token it
+ *  came from runs out (ms since the epoch); `gate` refuses it after that. */
+function switchIdentity(client: any, user: User, expires: number | undefined): void {
+  const prev = client.data?.identity as User | undefined;
+  if (prev && String(prev.id) !== String(user.id)) {
+    dropClientSubscriptions(client);
+  }
+  if (!client.data) client.data = {};
+  client.data.identity = user;
+  client.data.identityExpires = expires;
+}
+
+/** When a token's `exp` says it runs out, in ms since the epoch. */
+const expiresOf = (exp: unknown): number | undefined => (typeof exp === "number" ? exp * 1000 : undefined);
+
+export function jwtAuth(opts: JwtAuthOpts): DeltaAuth<User> {
+  const secret =
+    typeof opts.secret === "string"
+      ? new TextEncoder().encode(opts.secret)
+      : opts.secret;
+  const expirationTime = opts.expirationTime ?? "7d";
+  const loginSql = opts.loginSql ?? "SELECT login($1, $2) AS result";
+  const registerSql = opts.registerSql ?? "SELECT register($1, $2, $3) AS result";
+
+  async function signToken(user: User): Promise<string> {
+    return new SignJWT({
+      sub: String(user.id),
+      name: user.name,
+      email: user.email,
+    })
+      .setProtectedHeader({ alg: JWT_ALG })
+      .setIssuedAt()
+      .setExpirationTime(expirationTime)
+      .sign(secret);
+  }
+
+  async function verifyToken(token: string): Promise<{ user: User; expires: number | undefined } | null> {
+    try {
+      // Pin the algorithm allowlist — without it, jose accepts any alg the
+      // token header claims, opening an alg-confusion vector.
+      const { payload } = await jwtVerify(token, secret, { algorithms: [JWT_ALG] });
+      const id = payload.sub;
+      if (id === undefined) return null;
+      const user: User = {
+        id: /^\d+$/.test(String(id)) ? Number(id) : String(id),
+        name: payload.name as string | undefined,
+        email: payload.email as string | undefined,
+      };
+      return { user, expires: expiresOf(payload.exp) };
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    actions: {
+      async login(params, client) {
+        const { email, password } = params ?? {};
+        if (!email || !password) return { error: "email and password required" };
+        const { rows } = await opts.pool.query(loginSql, [email, password]);
+        const user = rows[0]?.result as User | null;
+        if (!user) return { error: "Invalid credentials" };
+        const token = await signToken(user);
+        switchIdentity(client, user, expiresOf(decodeJwt(token).exp));
+        log.info(`login user=${user.id}`);
+        return { result: { ...user, token } };
+      },
+
+      async register(params, client) {
+        const { name, email, password } = params ?? {};
+        if (!name || !email || !password) {
+          return { error: "name, email, and password required" };
+        }
+        try {
+          const { rows } = await opts.pool.query(registerSql, [name, email, password]);
+          const user = rows[0]?.result as User;
+          const token = await signToken(user);
+          switchIdentity(client, user, expiresOf(decodeJwt(token).exp));
+          log.info(`register user=${user.id}`);
+          return { result: { ...user, token } };
+        } catch (err: any) {
+          if (err.code === "23505") return { error: "Email already registered" };
+          throw err;
+        }
+      },
+
+      async authenticate(params, client) {
+        const { token } = params ?? {};
+        if (!token) return { error: "token required" };
+        const verified = await verifyToken(token);
+        if (!verified) return { error: "Invalid token" };
+        let user = verified.user;
+        if (opts.verifyUser) {
+          const checked = await opts.verifyUser(user, opts.pool);
+          if (!checked) return { error: "Invalid token" };
+          user = checked;
+        }
+        switchIdentity(client, user, verified.expires);
+        log.info(`authenticate user=${user.id}`);
+        return { result: user };
+      },
+
+      async logout(_params, client) {
+        const prev = client.data?.identity as User | undefined;
+        if (client.data) { delete client.data.identity; delete client.data.identityExpires; }
+        // Tear down the prior identity's live doc subscriptions so its scoped
+        // ops stop streaming to this socket immediately.
+        dropClientSubscriptions(client);
+        if (prev) log.info(`logout user=${prev.id}`);
+        return { result: { ack: true } };
+      },
+    },
+
+    gate(client) {
+      // A session lasts as long as its token: once it runs out the socket is
+      // signed out (and its documents let go), as a logout would do, and says
+      // so until it signs in again -- the listener asks the gate before it
+      // tells a socket of a change, too, so that is not always a request.
+      const expires = client.data?.identityExpires as number | undefined;
+      if (expires !== undefined && Date.now() >= expires) {
+        if (client.data.identity !== undefined) {
+          delete client.data.identity;
+          dropClientSubscriptions(client);
+        }
+        return { error: "Session expired: authenticate again" };
+      }
+      const identity = client.data?.identity as User | undefined;
+      if (!identity) return { error: "Authentication required" };
+      return identity;
+    },
+
+    asSqlArg(identity) {
+      return identity.id;
+    },
+  };
+}