dzql 0.7.0 → 0.9.0

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;
+    },
+  };
+}

package/src/postgres/auth.ts

@@ -0,0 +1,50 @@
+/**
+ * Postgres auth helpers — RLS session context for delta-doc queries.
+ *
+ * `withAppAuth(pool, sqlArg, fn)` checks out a client, opens a transaction,
+ * sets `app.user_id` for the duration of the transaction, runs `fn` with the
+ * client, then commits and releases. Row-Level Security policies that read
+ * `current_setting('app.user_id', true)` then filter automatically.
+ *
+ *   CREATE POLICY venues_owner ON venues
+ *     FOR ALL USING (owner_id = current_setting('app.user_id', true)::int);
+ *
+ *   await withAppAuth(pool, user.id, c =>
+ *     c.query("SELECT delta_open($1) AS doc", [docName]),
+ *   );
+ *
+ * The session variable is set via `SET LOCAL` so it reverts on transaction
+ * end — safe against pool reuse.
+ *
+ * Re-exports the `DeltaAuth` contract from `../auth` for convenience.
+ */
+import type { Pool, PoolClient } from "pg";
+
+export type { DeltaAuth, AuthError, AuthAction } from "@blueshed/delta/auth";
+export { isAuthError, wireAuth, upgradeWithAuth } from "@blueshed/delta/auth";
+
+/**
+ * Run `fn` inside a transaction with `SET LOCAL app.user_id = <sqlArg>`. All
+ * queries issued on the passed client observe RLS policies scoped to that
+ * identity.
+ */
+export async function withAppAuth<T>(
+  pool: Pool,
+  sqlArg: string | number,
+  fn: (c: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    // SET LOCAL cannot be parameterised — use set_config(..., is_local=true).
+    await client.query("SELECT set_config('app.user_id', $1, true)", [String(sqlArg)]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (err) {
+    try { await client.query("ROLLBACK"); } catch { /* pool may already be closed */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}

package/src/postgres/bootstrap.ts

@@ -0,0 +1,55 @@
+/**
+ * Bootstrap helpers — apply the delta-doc framework SQL to a Postgres
+ * database, programmatically. Alternative to copying the files into a
+ * consumer's `init_db/` directory.
+ *
+ *   import { Pool } from "pg";
+ *   import { applyFramework } from "@blueshed/delta/postgres";
+ *
+ *   const pool = new Pool({ connectionString: process.env.PG_URL });
+ *   await applyFramework(pool);
+ *
+ * The framework SQL is idempotent (`CREATE … IF NOT EXISTS`,
+ * `ON CONFLICT DO UPDATE`) so it is safe to call on every server boot.
+ *
+ * For docker-entrypoint-initdb.d workflows, use the `delta init` CLI to
+ * copy the same files into a directory the image can mount.
+ */
+import type { Pool } from "pg";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const FRAMEWORK_SQL_DIR = join(import.meta.dir, "..", "sql");
+
+/** Absolute paths to the framework SQL files, in apply-order.
+ *  Filters to `001*-*.sql` — siblings like `auth-jwt.sql` are applied
+ *  separately (see `@blueshed/delta/auth-jwt` → `applyAuthJwtSchema`). */
+export function frameworkSqlFiles(): string[] {
+  return readdirSync(FRAMEWORK_SQL_DIR)
+    .filter((f) => /^001[a-z]?-.+\.sql$/.test(f))
+    .sort()
+    .map((f) => join(FRAMEWORK_SQL_DIR, f));
+}
+
+/**
+ * Apply the framework SQL to the given pool. Runs every `001*` file in
+ * `src/sql/` alphabetically — 001a through 001g today. Safe to call
+ * repeatedly (idempotent statements).
+ */
+export async function applyFramework(pool: Pool): Promise<void> {
+  for (const path of frameworkSqlFiles()) {
+    const sql = readFileSync(path, "utf8");
+    await pool.query(sql);
+  }
+}
+
+/**
+ * Apply an arbitrary SQL string to the pool (convenience wrapper). Useful
+ * for layering `generateSql(schema, docs)` output on top of the framework:
+ *
+ *   await applyFramework(pool);
+ *   await applySql(pool, generateSql(schema, docs));
+ */
+export async function applySql(pool: Pool, sql: string): Promise<void> {
+  if (sql.trim()) await pool.query(sql);
+}

package/src/postgres/carry.ts

@@ -0,0 +1,40 @@
+/**
+ * Carrying an app's rows into, and out of, a Postgres database -- a server, or
+ * PGlite in this process. The same `Snapshot` every backend gives and takes
+ * (`../../schema`), so the data moves along the path with its ids and
+ * sequences unchanged.
+ */
+import type { Pool } from "pg";
+import { isoTime, lastId, q, type Schema, type Snapshot } from "@blueshed/delta/backend";
+
+/** Every row of the schema's tables (every version of a temporal row), and each sequence's last id. */
+export async function exportTables(pool: Pool, schema: Schema): Promise<Snapshot> {
+  const tables: Snapshot["tables"] = {};
+  const sequences: Record<string, number> = {};
+  for (const [key, table] of Object.entries(schema.tables)) {
+    const order = table.temporal ? "id, valid_from" : "id";
+    const { rows } = await pool.query(`SELECT to_jsonb(t.*) AS row FROM ${q(table.name)} t ORDER BY ${order}`);
+    tables[key] = rows.map(({ row }: { row: Record<string, unknown> }) =>
+      table.temporal ? { ...row, valid_from: isoTime(row.valid_from), valid_to: isoTime(row.valid_to) } : row,
+    );
+    const seq = (await pool.query(`SELECT last_value, is_called FROM ${q(`seq_${table.name}`)}`)).rows[0];
+    sequences[key] = seq ? Number(seq.last_value) - (seq.is_called ? 0 : 1) : 0;
+  }
+  return { tables, sequences };
+}
+
+/**
+ * Put a snapshot's rows into the schema's tables, as they are (ids kept), and
+ * set each sequence past them, so the next row the database names follows the
+ * last one named where the rows came from. The tables should be empty.
+ */
+export async function importTables(pool: Pool, schema: Schema, snapshot: Snapshot): Promise<void> {
+  for (const [key, table] of Object.entries(schema.tables)) {
+    for (const row of snapshot.tables[key] ?? []) {
+      const value = table.temporal ? { valid_from: new Date().toISOString(), valid_to: null, ...row } : row;
+      await pool.query(`INSERT INTO ${q(table.name)} SELECT * FROM jsonb_populate_record(null::${q(table.name)}, $1)`, [JSON.stringify(value)]);
+    }
+    const last = lastId(snapshot, key);
+    await pool.query(`SELECT setval($1, $2, $3)`, [`seq_${table.name}`, Math.max(last, 1), last > 0]);
+  }
+}