@facilis.dev/db 0.0.0-stage → 0.1.0

package/src/read-only-sql.ts

@@ -0,0 +1,156 @@
+// Static guards for SQL text that reaches a read-only surface (SPEC §11.2).
+//
+// These checks are the UX half of the contract: the dev query endpoint wraps every
+// statement in a read-only transaction, which is what actually rejects writes. They still
+// matter where a query is inlined into another statement — a view definition is embedded
+// in CREATE VIEW, so a second statement must never slip through, and a prefix check alone
+// would accept "select 1; drop table todos".
+
+const READ_ONLY_KEYWORDS: ReadonlySet<string> = new Set(["SELECT", "WITH", "VALUES", "TABLE"]);
+
+/** True for a single read-only statement: SELECT, WITH, VALUES or TABLE. */
+export function isReadOnlySql(text: string): boolean {
+  const keyword = firstKeyword(text);
+  if (keyword === null || !READ_ONLY_KEYWORDS.has(keyword)) return false;
+  return !hasMultipleStatements(text);
+}
+
+/** The statement without a trailing semicolon, for embedding in a wrapper or in DDL. */
+export function stripTrailingSemicolon(text: string): string {
+  return text.trim().replace(/;\s*$/, "");
+}
+
+type ScanState =
+  { kind: "normal" } | { kind: "single" } | { kind: "double" } | { kind: "dollar"; tag: string };
+
+interface Cursor {
+  readonly text: string;
+  index: number;
+}
+
+function isSpace(ch: string): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v";
+}
+
+/** True when the text at `cursor.index` starts a comment; advances past it when so. */
+function skipComment(cursor: Cursor): boolean {
+  const { text, index } = cursor;
+  if (text[index] === "-" && text[index + 1] === "-") {
+    const newline = text.indexOf("\n", index + 2);
+    cursor.index = newline === -1 ? text.length : newline + 1;
+    return true;
+  }
+  if (text[index] === "/" && text[index + 1] === "*") {
+    // Postgres block comments nest; count them so an inner comment cannot end the outer.
+    let depth = 1;
+    let at = index + 2;
+    while (at < text.length && depth > 0) {
+      if (text[at] === "/" && text[at + 1] === "*") {
+        depth += 1;
+        at += 2;
+        continue;
+      }
+      if (text[at] === "*" && text[at + 1] === "/") {
+        depth -= 1;
+        at += 2;
+        continue;
+      }
+      at += 1;
+    }
+    cursor.index = at;
+    return true;
+  }
+  return false;
+}
+
+/** The first keyword of the statement, comments and whitespace skipped. */
+export function firstKeyword(text: string): string | null {
+  const cursor: Cursor = { text, index: 0 };
+  while (cursor.index < text.length) {
+    while (cursor.index < text.length && isSpace(text[cursor.index] ?? "")) cursor.index += 1;
+    if (skipComment(cursor)) continue;
+    break;
+  }
+  const match = /^[A-Za-z]+/.exec(text.slice(cursor.index));
+  return match === null ? null : match[0].toUpperCase();
+}
+
+/**
+ * True when a ';' is followed by anything but comments/whitespace, or by another ';'.
+ * Backslashes are NOT treated as escapes: standard_conforming_strings is on, and a
+ * missed closing quote would make the scanner swallow a real statement separator (a
+ * false "single statement" is the one answer this must never give).
+ */
+export function hasMultipleStatements(text: string): boolean {
+  const cursor: Cursor = { text, index: 0 };
+  let state: ScanState = { kind: "normal" };
+  let separatorSeen = false;
+
+  while (cursor.index < text.length) {
+    const ch = text[cursor.index] ?? "";
+    if (state.kind === "normal") {
+      if (skipComment(cursor)) continue;
+      if (isSpace(ch)) {
+        cursor.index += 1;
+        continue;
+      }
+      if (separatorSeen) return true;
+      if (ch === "'") {
+        state = { kind: "single" };
+        cursor.index += 1;
+        continue;
+      }
+      if (ch === '"') {
+        state = { kind: "double" };
+        cursor.index += 1;
+        continue;
+      }
+      if (ch === "$") {
+        const tag = dollarTagAt(text, cursor.index);
+        if (tag !== null) {
+          state = { kind: "dollar", tag };
+          cursor.index += tag.length;
+          continue;
+        }
+      }
+      if (ch === ";") separatorSeen = true;
+      cursor.index += 1;
+      continue;
+    }
+    if (state.kind === "single") {
+      if (ch === "'") {
+        if (text[cursor.index + 1] === "'") {
+          cursor.index += 2;
+          continue;
+        }
+        state = { kind: "normal" };
+      }
+      cursor.index += 1;
+      continue;
+    }
+    if (state.kind === "double") {
+      if (ch === '"') {
+        if (text[cursor.index + 1] === '"') {
+          cursor.index += 2;
+          continue;
+        }
+        state = { kind: "normal" };
+      }
+      cursor.index += 1;
+      continue;
+    }
+    if (text.startsWith(state.tag, cursor.index)) {
+      cursor.index += state.tag.length;
+      state = { kind: "normal" };
+      continue;
+    }
+    cursor.index += 1;
+  }
+  return false;
+}
+
+/** A complete dollar-quote tag (`$tag$`) at `index`, or null for a positional parameter. */
+function dollarTagAt(text: string, index: number): string | null {
+  const match = /^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/.exec(text.slice(index));
+  return match === null ? null : match[0];
+}

package/src/rls.ts

@@ -0,0 +1,109 @@
+import { sql } from "drizzle-orm";
+import { PgDialect, pgPolicy, type PgPolicy, type PgPolicyToOption } from "drizzle-orm/pg-core";
+
+const dialect = new PgDialect();
+
+/** Row-level-security extras returned by `rlsForTable` for a pgTable definition. */
+export interface RlsOptions {
+  readonly tenantColumn?: string;
+  readonly ownerColumn?: string;
+  readonly rolesColumn?: string;
+}
+
+export interface RlsExtras {
+  readonly enableRLS: true;
+  readonly policies: PgPolicy[];
+}
+
+/**
+ * Tenant isolation as a RESTRICTIVE policy. Deviation from SPEC §8.4.5's original SQL:
+ * as written there the policy is permissive, and Postgres ORs permissive policies, so
+ * role/owner clauses let callers cross tenants. D-008 (Phase 0 evidence) fixes this by
+ * making tenant isolation RESTRICTIVE (always AND-ed); this generator emits that form.
+ */
+export function tenantIsolationPolicy(column = "tenant_id"): PgPolicy {
+  return pgPolicy("tenant_isolation", {
+    as: "restrictive",
+    for: "all",
+    using: tenantPredicate(column),
+    withCheck: tenantPredicate(column),
+  });
+}
+
+/** Permissive policy granting a caller rows they own (SPEC §8.4.5 owner clause). */
+
+export function ownerIsolationPolicy(column = "owner_id"): PgPolicy {
+  return pgPolicy("owner_isolation", {
+    for: "all",
+    using: ownerPredicate(column),
+    withCheck: ownerPredicate(column),
+  });
+}
+
+/**
+ * Permissive role policy: a row is visible when the row's `column` names one of the
+ * caller's app roles (`app.roles::jsonb ? column`). Columns hold a role name such as
+ * "admin"; roles themselves are never Postgres roles (SPEC §8.4.5).
+ */
+export function rolePolicy(column: string, policyName = "role_access"): PgPolicy {
+  return pgPolicy(policyName, {
+    for: "all",
+    using: rolePredicate(column),
+    withCheck: rolePredicate(column),
+  });
+}
+
+/**
+ * Builds the standard policy set for a scoped table. Use as
+ * `pgTable(..., () => rlsForTable({ tenantColumn }).policies).enableRLS()`.
+ * (`enableRLS` is returned so callers can assert/forward the flag; Drizzle applies it
+ * through `.enableRLS()`, since pgTable's extras callback only accepts config values.)
+ */
+export function rlsForTable(options: RlsOptions = {}): RlsExtras {
+  const policies: PgPolicy[] = [tenantIsolationPolicy(options.tenantColumn)];
+  if (options.ownerColumn !== undefined) policies.push(ownerIsolationPolicy(options.ownerColumn));
+  if (options.rolesColumn !== undefined) policies.push(rolePolicy(options.rolesColumn));
+  return { enableRLS: true, policies };
+}
+
+/** Alias kept for the wording used in the Phase 1 contracts file. */
+export const withRls = rlsForTable;
+
+/** Renders a complete CREATE POLICY statement (used by migrations and the manifest). */
+export function policyCreateSql(tableName: string, policy: PgPolicy): string {
+  const parts = [`CREATE POLICY ${quoteIdentifier(policy.name)} ON ${quoteIdentifier(tableName)}`];
+  if (policy.as !== undefined) parts.push(`AS ${policy.as.toUpperCase()}`);
+  parts.push(`FOR ${(policy.for ?? "all").toUpperCase()}`);
+  if (policy.to !== undefined) parts.push(`TO ${policyToList(policy.to)}`);
+  if (policy.using !== undefined) parts.push(`USING (${dialect.sqlToQuery(policy.using).sql})`);
+  if (policy.withCheck !== undefined) {
+    parts.push(`WITH CHECK (${dialect.sqlToQuery(policy.withCheck).sql})`);
+  }
+  return `${parts.join(" ")};`;
+}
+
+function tenantPredicate(column: string) {
+  return sql`${sql.identifier(column)} = nullif(current_setting('app.tenant_id', true), '')::uuid`;
+}
+
+function ownerPredicate(column: string) {
+  return sql`${sql.identifier(column)} = nullif(current_setting('app.user_id', true), '')::uuid`;
+}
+
+function rolePredicate(column: string) {
+  return sql`nullif(current_setting('app.roles', true), '')::jsonb ? ${sql.identifier(column)}`;
+}
+
+function quoteIdentifier(name: string): string {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+function policyToList(to: PgPolicyToOption): string {
+  if (Array.isArray(to)) return to.map((entry) => policyToList(entry)).join(", ");
+  if (typeof to === "string") {
+    return ["public", "current_role", "current_user", "session_user"].includes(to)
+      ? to.toUpperCase()
+      : quoteIdentifier(to);
+  }
+  return quoteIdentifier(to.name);
+}

package/src/schema-digest.ts

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+
+import type {
+  LiveColumnSnapshot,
+  LiveSchemaSnapshot,
+  LivePolicySnapshot,
+  LiveTableSnapshot,
+} from "./live-schema.ts";
+import { canonicalColumnType, isRestrictivePolicy, normalizePolicySql } from "./schema-drift.ts";
+import type { ColumnSnapshot, PolicySnapshot, SchemaSnapshot, TableSnapshot } from "./snapshot.ts";
+
+/**
+ * Canonical schema digest (docs/MIGRATION-PLAN.md §3.1, ADR D-159).
+ *
+ * The declared snapshot (`schemaSnapshot`, from `db/schema.ts`) and the live snapshot
+ * (`liveSchemaSnapshot`, from the Postgres catalogs) are projected onto one canonical
+ * form and hashed. A release artifact carries these digests as `fromDigest`/`toDigest`;
+ * the deploy uses them to check that the database is where the ledger says it is.
+ *
+ * Equality is fail-closed by construction: only the normalization described below is
+ * applied, everything else is a difference, so two different schemas cannot share a
+ * digest and a declared schema and the catalog it produces can.
+ *
+ * Digest scope v1 — the first segment of the digest string is the version:
+ * - table: name, `rlsEnabled`;
+ * - column: name, canonical SQL type (`canonicalColumnType`), `notNull`, canonical
+ *   default (`normalizeDefault`), `isPrimaryKey`;
+ * - policy: name, command upper-cased, restrictive flag, normalized USING and WITH CHECK
+ *   predicates (`normalizePolicySql`, shared with `diffSchemaSnapshots`).
+ *
+ * NOT in v1: foreign keys, indexes, unique/check constraints, enum types, scope columns,
+ * policy roles and the table's schema (framework tables live in the connection's current
+ * schema, i.e. `public`). They join the projection in v2, which changes the digest string
+ * prefix too, so a v1 digest is never compared with a v2 one.
+ *
+ * Framework bookkeeping tables never reach the projection: `liveSchemaSnapshot` filters
+ * the migration tracking table and reads only the current schema, and declared snapshots
+ * contain only project tables.
+ */
+export const SCHEMA_DIGEST_VERSION = 1;
+
+export interface DigestColumn {
+  readonly name: string;
+  /** `canonicalColumnType` spelling, e.g. `varchar(120)` or `timestamp with time zone`. */
+  readonly type: string;
+  readonly notNull: boolean;
+  /** `normalizeDefault` form; null means the column has no default. */
+  readonly default: string | null;
+  readonly isPrimaryKey: boolean;
+}
+
+export interface DigestPolicy {
+  readonly name: string;
+  /** SQL command, upper-cased: SELECT, INSERT, UPDATE, DELETE or ALL. */
+  readonly command: string;
+  /** RESTRICTIVE policies are AND-ed with the permissive set (D-008). */
+  readonly restrictive: boolean;
+  /** `normalizePolicySql` form; "" means the policy has no USING clause. */
+  readonly using: string;
+  /** `normalizePolicySql` form; "" means the policy has no WITH CHECK clause. */
+  readonly withCheck: string;
+}
+
+export interface DigestTable {
+  readonly name: string;
+  readonly rlsEnabled: boolean;
+  /** Sorted by name: `ordinal_position` is not part of the projection. */
+  readonly columns: readonly DigestColumn[];
+  /** Sorted by name. */
+  readonly policies: readonly DigestPolicy[];
+}
+
+export interface DigestSchema {
+  /** Projection version; part of the canonical JSON and of the digest string prefix. */
+  readonly digestVersion: number;
+  /** Sorted by name. */
+  readonly tables: readonly DigestTable[];
+}
+
+/** Project the declared (Drizzle) snapshot onto the canonical form. */
+export function declaredDigestSchema(snapshot: SchemaSnapshot): DigestSchema {
+  return {
+    digestVersion: SCHEMA_DIGEST_VERSION,
+    tables: snapshot.tables.map(declaredDigestTable).toSorted(byName),
+  };
+}
+
+/** Project the live (catalog) snapshot onto the same canonical form. */
+export function liveDigestSchema(snapshot: LiveSchemaSnapshot): DigestSchema {
+  return {
+    digestVersion: SCHEMA_DIGEST_VERSION,
+    tables: snapshot.tables.map(liveDigestTable).toSorted(byName),
+  };
+}
+
+function declaredDigestTable(table: TableSnapshot): DigestTable {
+  return {
+    name: table.name,
+    rlsEnabled: table.rlsEnabled,
+    columns: table.columns.map(declaredDigestColumn).toSorted(byName),
+    policies: table.policies.map(declaredDigestPolicy).toSorted(byName),
+  };
+}
+
+function liveDigestTable(table: LiveTableSnapshot): DigestTable {
+  return {
+    name: table.name,
+    rlsEnabled: table.rlsEnabled,
+    columns: table.columns.map(liveDigestColumn).toSorted(byName),
+    policies: table.policies.map(liveDigestPolicy).toSorted(byName),
+  };
+}
+
+function declaredDigestColumn(column: ColumnSnapshot): DigestColumn {
+  return {
+    name: column.name,
+    type: canonicalColumnType(column.type),
+    notNull: column.notNull,
+    default: normalizeDefault(column.default),
+    isPrimaryKey: column.isPrimaryKey,
+  };
+}
+
+function liveDigestColumn(column: LiveColumnSnapshot): DigestColumn {
+  return {
+    name: column.name,
+    type: canonicalColumnType(column.type),
+    notNull: column.notNull,
+    default: normalizeDefault(column.default),
+    isPrimaryKey: column.isPrimaryKey,
+  };
+}
+
+function declaredDigestPolicy(policy: PolicySnapshot): DigestPolicy {
+  return {
+    name: policy.name,
+    command: policy.command.toUpperCase(),
+    restrictive: isRestrictivePolicy(policy),
+    using: normalizePolicySql(policy.using),
+    withCheck: normalizePolicySql(policy.withCheck),
+  };
+}
+
+function liveDigestPolicy(policy: LivePolicySnapshot): DigestPolicy {
+  return {
+    name: policy.name,
+    command: policy.command.toUpperCase(),
+    restrictive: policy.restrictive,
+    using: normalizePolicySql(policy.using),
+    withCheck: normalizePolicySql(policy.withCheck),
+  };
+}
+
+/**
+ * Canonical JSON: object keys sorted by code unit at every level, no whitespace, arrays in
+ * the order the projection produced (already sorted by their semantic key).
+ */
+export function canonicalDigestJson(schema: DigestSchema): string {
+  return JSON.stringify(sortKeys(schema));
+}
+
+/**
+ * sha256 of the canonical form, spelled `v<version>:sha256:<64 lowercase hex>`. The
+ * version prefix is part of the value on purpose: a digest computed under a different
+ * projection must not compare equal to this one.
+ */
+export function digestSchema(schema: DigestSchema): string {
+  const hash = createHash("sha256").update(canonicalDigestJson(schema), "utf8").digest("hex");
+  return `v${schema.digestVersion}:sha256:${hash}`;
+}
+
+/**
+ * Code-unit comparison, not `localeCompare`: the digest must not depend on the ICU locale
+ * of the machine (or browser) that computes it.
+ */
+function compareText(left: string, right: string): number {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function byName(left: { readonly name: string }, right: { readonly name: string }): number {
+  return compareText(left.name, right.name);
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .toSorted(compareText)
+        .map((key) => [key, sortKeys(record[key])]),
+    );
+  }
+  return value;
+}
+
+/** A cast suffix: the column type is already part of the projection, so casts are noise. */
+const TYPE_CAST = /::[a-z][a-z_ ]*(?:\([0-9, ]*\))?(?:\[\])?/g;
+/** Single-quoted SQL literal, including the doubled-quote escape (`''`). */
+const STRING_LITERAL = /'(?:[^']|'')*'/g;
+
+/**
+ * Normalize a column default onto the spelling both renderers agree on.
+ *
+ * Drizzle (`schemaSnapshot`) renders `'untitled'`, `false`, `now()`; `pg_get_expr`
+ * (`liveSchemaSnapshot`) renders `'untitled'::text`, `false`, `now()`. The differences
+ * are catalog-only noise: explicit casts, keyword case, redundant parentheses and
+ * whitespace. String-literal bodies are preserved verbatim, so `'Draft'` and `'draft'`
+ * stay different defaults (guessed normalization here would turn drift into a digest
+ * match). `CURRENT_TIMESTAMP` is folded onto `now` because Postgres stores both as
+ * `now()`.
+ *
+ * NOT normalized (documented v1 limitations): JSON object/array defaults (`{}` vs
+ * `'{}'::jsonb`), date values rendered as full ISO timestamps by Drizzle, array defaults
+ * and sequences of `serial` columns. P2's renderer owns producing catalog-compatible
+ * defaults; until then such a column is a digest difference, never a false match.
+ */
+export function normalizeDefault(value: string | null): string | null {
+  if (value === null) return null;
+  let normalized = "";
+  let cursor = 0;
+  for (const match of value.matchAll(STRING_LITERAL)) {
+    const start = match.index ?? 0;
+    normalized += normalizeDefaultFragment(value.slice(cursor, start));
+    normalized += match[0];
+    cursor = start + match[0].length;
+  }
+  normalized += normalizeDefaultFragment(value.slice(cursor));
+  return normalized;
+}
+
+function normalizeDefaultFragment(fragment: string): string {
+  return fragment
+    .toLowerCase()
+    .replace(TYPE_CAST, "")
+    .replace(/[()]/g, "")
+    .replace(/\bcurrent_timestamp\b/g, "now")
+    .replace(/\s+/g, "");
+}