okengine 0.14.1 → 0.15.2

package/src/elements/store/schema-decl.ts

@@ -69,6 +69,42 @@ export interface SchemaColumnDecl extends ColumnDef {
   getSQL(): never;
 }
 
+/** Policy command on a {@link SchemaPolicyDecl}. */
+export type SchemaPolicyFor = "all" | "select" | "insert" | "update" | "delete";
+
+/** Policy behavior on a {@link SchemaPolicyDecl}. */
+export type SchemaPolicyAs = "permissive" | "restrictive";
+
+/**
+ * Drizzle-shaped policy extra (`pgPolicy` emit).
+ */
+export interface SchemaPolicyDecl {
+  readonly kind: "schema-policy";
+  readonly name: string;
+  readonly as?: SchemaPolicyAs;
+  readonly to?: string | readonly string[];
+  readonly for?: SchemaPolicyFor;
+  readonly using?: string;
+  readonly withCheck?: string;
+}
+
+/** Enable RLS with no policies (`pgTable.withRLS`). */
+export interface SchemaRlsEnableDecl {
+  readonly kind: "schema-rls";
+}
+
+/** Third-arg extra for {@link schemaTable}. */
+export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl;
+
+/** Options for {@link schemaPolicy} / Gate helpers. */
+export interface SchemaPolicyOptions {
+  readonly as?: SchemaPolicyAs;
+  readonly to?: string | readonly string[];
+  readonly for?: SchemaPolicyFor;
+  readonly using?: string;
+  readonly withCheck?: string;
+}
+
 /** Table from {@link store.schema.table} — extends {@link TableHandle}. */
 export interface SchemaTableDecl extends TableHandle {
   readonly kind: "schema-table";
@@ -78,6 +114,10 @@ export interface SchemaTableDecl extends TableHandle {
    * (spreading columns would otherwise shadow {@link TableHandle.name}).
    */
   readonly tableName?: string;
+  /** `true` when {@link schemaRls} was declared or any policy is present. */
+  readonly rls?: boolean;
+  /** Declared policies (emit + Manifest). */
+  readonly policies?: readonly SchemaPolicyDecl[];
 }
 
 /** Fluent field builder before key finalization. */
@@ -310,20 +350,28 @@ export type SchemaTableWithColumns<
  *
  * @param name - SQL table name
  * @param columns - Column map using {@link field} builders
+ * @param extras - RLS enable + {@link schemaPolicy} extras (Drizzle third arg)
  */
 export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   name: string,
   columns: C,
+  extras: readonly SchemaTableExtra[] = [],
 ): SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }> {
   const finalized = finalizeColumnMap(columns);
   const stamped: Record<string, SchemaColumnDecl> = {};
   for (const [key, col] of Object.entries(finalized)) {
     stamped[key] = { ...col, tableName: name };
   }
+  const policies = extras.filter(
+    (extra): extra is SchemaPolicyDecl => extra.kind === "schema-policy",
+  );
+  const rls = extras.some((extra) => extra.kind === "schema-rls") || policies.length > 0;
   const table = {
     name,
     columns: stamped,
     ...stamped,
+    ...(rls ? { rls: true } : {}),
+    ...(policies.length > 0 ? { policies } : {}),
   };
   // Survive columns named `name` or `kind` (they would otherwise shadow
   // the table discriminant / SQL name).
@@ -332,6 +380,117 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   return table as SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }>;
 }
 
+/**
+ * Enable RLS with no policies (`pgTable.withRLS`).
+ */
+export function schemaRls(): SchemaRlsEnableDecl {
+  return { kind: "schema-rls" };
+}
+
+/**
+ * Raw Drizzle-shaped policy extra.
+ *
+ * @param name - Policy name
+ * @param options - `as` / `to` / `for` / `using` / `withCheck`
+ */
+export function schemaPolicy(name: string, options: SchemaPolicyOptions = {}): SchemaPolicyDecl {
+  return {
+    kind: "schema-policy",
+    name,
+    ...(options.as !== undefined ? { as: options.as } : {}),
+    ...(options.to !== undefined ? { to: options.to } : {}),
+    ...(options.for !== undefined ? { for: options.for } : {}),
+    ...(options.using !== undefined ? { using: options.using } : {}),
+    ...(options.withCheck !== undefined ? { withCheck: options.withCheck } : {}),
+  };
+}
+
+function sqlStringLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function helperPolicyName(prefix: string, key: string, command: SchemaPolicyFor): string {
+  const slug = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "");
+  return `${prefix}_${slug}_${command}`;
+}
+
+function policyPredicates(
+  command: SchemaPolicyFor,
+  expr: string,
+): { readonly using?: string; readonly withCheck?: string } {
+  if (command === "insert") return { withCheck: expr };
+  if (command === "update" || command === "all") return { using: expr, withCheck: expr };
+  return { using: expr };
+}
+
+/**
+ * Gate-name policy — `oke.gate() = 'member'`.
+ *
+ * @param gate - Policy / public Gate name
+ * @param options - Command (default `select`)
+ */
+export function schemaPolicyGate(
+  gate: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "select";
+  return schemaPolicy(helperPolicyName("gate", gate, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `oke.gate() = ${sqlStringLiteral(gate)}`),
+  });
+}
+
+/**
+ * Owner-column policy — `owner = oke.user()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function schemaPolicyOwner(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "all";
+  return schemaPolicy(helperPolicyName("owner", column, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `${column} = oke.user()`),
+  });
+}
+
+/**
+ * Scope policy — `oke.has_scope('booking:create')`.
+ *
+ * @param scope - Scope string
+ * @param options - Command (default `insert`)
+ */
+export function schemaPolicyScope(
+  scope: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "insert";
+  return schemaPolicy(helperPolicyName("scope", scope, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `oke.has_scope(${sqlStringLiteral(scope)})`),
+  });
+}
+
+/** Callable `store.schema.policy` plus Gate helpers. */
+export type SchemaPolicyApi = typeof schemaPolicy & {
+  readonly gate: typeof schemaPolicyGate;
+  readonly owner: typeof schemaPolicyOwner;
+  readonly scope: typeof schemaPolicyScope;
+};
+
+/** `store.schema.policy` — raw + Gate helpers. */
+export const schemaPolicyApi: SchemaPolicyApi = Object.assign(schemaPolicy, {
+  gate: schemaPolicyGate,
+  owner: schemaPolicyOwner,
+  scope: schemaPolicyScope,
+});
+
 // ─── Relations (mirrors drizzle-orm `defineRelations`) ───────────────────────
 
 /** Column path recorded by relation helpers (`r.links.code`). */
@@ -527,6 +686,8 @@ export function schemaRelations<T extends Readonly<Record<string, SchemaTableDec
 export const schema = {
   table: schemaTable,
   relations: schemaRelations,
+  rls: schemaRls,
+  policy: schemaPolicyApi,
 } as const;
 
 /**

package/src/elements/store/seed.ts

@@ -61,7 +61,7 @@ export function resolveSeedIdentity(
 }
 
 /**
- * Confirm copy for `oke dev` / `oke db seed` — names this app's seed.
+ * Confirm copy for `oke db seed` — names this app's seed.
  *
  * @param identity - Resolved {@link SeedIdentity}
  */

package/src/elements/store/sql-condition.test.ts

@@ -86,6 +86,18 @@ describe("compileWhere", () => {
     expect(c.params).toEqual(["n1", "t"]);
   });
 
+  test("legacy array-valued StringChunk fragments still compile", () => {
+    const c = compileWhere({
+      queryChunks: [
+        notes.id,
+        { constructor: { name: "StringChunk" }, value: [" = "] },
+        { value: "n1" },
+      ],
+    });
+    expect(c.clause).toBe(`"id" = ?`);
+    expect(c.params).toEqual(["n1"]);
+  });
+
   test("inArray expands one placeholder per value", () => {
     const c = compileWhere(inArray(notes.id, ["a", "b", "c"]));
     expect(c.clause).toBe(`"id" in (?, ?, ?)`);

package/src/elements/store/sql-condition.ts

@@ -333,10 +333,33 @@ function chunksOf(node: unknown): readonly unknown[] {
   return (node as { queryChunks: unknown[] }).queryChunks;
 }
 
-/** Joined text of a Drizzle `StringChunk` (`{ value: string[] }`). */
+/**
+ * True when `chunk` is a Drizzle `StringChunk` (or the synthetic array-valued
+ * shape `resource.ts` still emits). `Param` also has a `value` field — never
+ * treat those as SQL text.
+ */
+function isStringChunk(chunk: object): boolean {
+  const ctor = (chunk as { constructor?: { name?: unknown } }).constructor?.name;
+  if (ctor === "StringChunk") return true;
+  const value = (chunk as { value?: unknown }).value;
+  return (
+    Array.isArray(value) &&
+    value.every((part) => typeof part === "string") &&
+    !("encoder" in chunk) &&
+    !("name" in chunk)
+  );
+}
+
+/**
+ * Joined text of a Drizzle `StringChunk`.
+ *
+ * drizzle-orm `1.0.0-rc.5-169397b` stores `value` as a `string`. Earlier
+ * snapshots (and the synthetic chunks in `resource.ts`) store `string[]`.
+ */
 function chunkText(chunk: unknown): string | undefined {
-  if (!chunk || typeof chunk !== "object") return undefined;
+  if (!chunk || typeof chunk !== "object" || !isStringChunk(chunk)) return undefined;
   const value = (chunk as { value?: unknown }).value;
+  if (typeof value === "string") return value;
   return Array.isArray(value) ? value.join("") : undefined;
 }
 
@@ -394,6 +417,7 @@ function asParamValue(chunk: unknown): { readonly found: boolean; readonly value
   if (chunk === undefined) return { found: false };
   if (chunk === null || typeof chunk !== "object") return { found: true, value: chunk };
   if (Array.isArray(chunk)) return { found: false };
+  if (isStringChunk(chunk)) return { found: false };
   if (!("value" in (chunk as object))) return { found: false };
   if (Array.isArray((chunk as { value: unknown }).value)) return { found: false };
   if ((chunk as { name?: unknown }).name) return { found: false };

package/src/elements/store/sql-rls-isolation.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Real PGlite RLS isolation through {@link createSqlStoreHandle}.
+ *
+ * Covers the gap unit tests missed: a live policy, two concurrent identity
+ * bags on one shared connection, and row-level isolation. PGlite `query`
+ * rejects multi-command batches — the stamp is split statements pinned
+ * through `SqlConnection.transaction`.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { connectPglite } from "../../drivers/pglite.ts";
+import { connectPostgres } from "../../drivers/postgres.ts";
+import { installOkeRlsHelpers } from "../../drivers/pg-rls.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
+import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
+
+const NOTES_DDL = `CREATE TABLE notes (
+  id text PRIMARY KEY,
+  owner text NOT NULL,
+  body text NOT NULL
+)`;
+
+const OWNER_POLICY = `CREATE POLICY owner_select ON notes
+  AS PERMISSIVE FOR SELECT TO public
+  USING (owner = oke.user())`;
+
+/** File-scoped warmed PGlite. */
+let conn: SqlConnection;
+/** Stamped as alice. */
+let asAlice: SqlStoreHandle;
+/** Stamped as bob. */
+let asBob: SqlStoreHandle;
+/** No stamp — table-owner / superuser bypass. */
+let asOwner: SqlStoreHandle;
+
+beforeAll(async () => {
+  conn = await connectPglite({ url: "memory://sql-rls-isolation", role: "primary" });
+  await conn.exec(NOTES_DDL);
+  await conn.exec(`INSERT INTO notes VALUES ('a', 'alice', 'hi'), ('b', 'bob', 'yo')`);
+  await conn.exec(`ALTER TABLE notes ENABLE ROW LEVEL SECURITY`);
+  await installOkeRlsHelpers((sql) => conn.exec(sql));
+  await conn.exec(OWNER_POLICY);
+  asAlice = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+    rls: { gate: "member", userId: "alice", scopes: ["member"] },
+  });
+  asBob = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+    rls: { gate: "member", userId: "bob", scopes: ["member"] },
+  });
+  asOwner = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+  });
+}, 15_000);
+
+afterAll(async () => {
+  await conn.close();
+});
+
+describe("sql-session RLS isolation (pglite)", () => {
+  test("pglite query rejects a multi-command batch (the old prelude)", async () => {
+    await expect(
+      conn.query("BEGIN; SET LOCAL row_security = on; SELECT set_config('oke.user', $1, true)", [
+        "alice",
+      ]),
+    ).rejects.toThrow(/multiple commands/i);
+  });
+
+  test("sequential identities see only their rows", async () => {
+    const alice = await asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    const bob = await asBob.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    expect(alice).toEqual([{ id: "a", owner: "alice" }]);
+    expect(bob).toEqual([{ id: "b", owner: "bob" }]);
+  });
+
+  test("concurrent identities do not leak across the shared connection", async () => {
+    const [alice, bob, aliceAgain] = await Promise.all([
+      asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`),
+      asBob.raw(`SELECT id, owner FROM notes ORDER BY id`),
+      asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`),
+    ]);
+    expect(alice).toEqual([{ id: "a", owner: "alice" }]);
+    expect(bob).toEqual([{ id: "b", owner: "bob" }]);
+    expect(aliceAgain).toEqual([{ id: "a", owner: "alice" }]);
+  });
+
+  test("unstamped owner/superuser still sees every row", async () => {
+    const rows = await asOwner.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    expect(rows).toEqual([
+      { id: "a", owner: "alice" },
+      { id: "b", owner: "bob" },
+    ]);
+  });
+});
+
+const LIVE_PG =
+  process.env.OKE_TEST_DOCKER === "1" &&
+  (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL)?.startsWith("postgres");
+if (!LIVE_PG) {
+  console.log("skip: live Postgres RLS isolation needs OKE_TEST_DOCKER=1 and DATABASE_URL");
+}
+
+describe("sql-session RLS isolation (live postgres)", () => {
+  const live = LIVE_PG ? test : test.skip;
+  const table = "oke_rls_isolation_notes";
+
+  live(
+    "split stamp isolates concurrent identities",
+    async () => {
+      const pg = await connectPostgres({
+        url: process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL,
+        role: "primary",
+      });
+      try {
+        await pg.exec(`DROP TABLE IF EXISTS ${table}`);
+        await pg.exec(
+          `CREATE TABLE ${table} (id text PRIMARY KEY, owner text NOT NULL, body text NOT NULL)`,
+        );
+        await pg.exec(`INSERT INTO ${table} VALUES ('a', 'alice', 'hi'), ('b', 'bob', 'yo')`);
+        await pg.exec(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY`);
+        await installOkeRlsHelpers((sql) => pg.exec(sql));
+        await pg.exec(
+          `CREATE POLICY owner_select ON ${table} AS PERMISSIVE FOR SELECT TO public USING (owner = oke.user())`,
+        );
+        const alice = createSqlStoreHandle("sql:app", {
+          connection: pg,
+          classifications: new Map(),
+          routedRole: "primary",
+          domainDdl: "off",
+          rls: { gate: "member", userId: "alice", scopes: ["member"] },
+        });
+        const bob = createSqlStoreHandle("sql:app", {
+          connection: pg,
+          classifications: new Map(),
+          routedRole: "primary",
+          domainDdl: "off",
+          rls: { gate: "member", userId: "bob", scopes: ["member"] },
+        });
+        const [a, b] = await Promise.all([
+          alice.raw(`SELECT id, owner FROM ${table} ORDER BY id`),
+          bob.raw(`SELECT id, owner FROM ${table} ORDER BY id`),
+        ]);
+        expect(a).toEqual([{ id: "a", owner: "alice" }]);
+        expect(b).toEqual([{ id: "b", owner: "bob" }]);
+      } finally {
+        try {
+          await pg.exec(`DROP TABLE IF EXISTS ${table}`);
+        } catch {
+          // Best-effort cleanup.
+        }
+        await pg.close();
+      }
+    },
+    20_000,
+  );
+});

package/src/elements/store/sql-rls-stamp.test.ts

@@ -0,0 +1,117 @@
+/**
+ * RLS stamps on pooled postgres must `reserve()` one slot, then BEGIN/SET
+ * on that slot. `begin()` + parent `unsafe()` checkouts a second slot and
+ * deadlocks a tiny pool (`checkout timeout` from PgDog).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { connectPostgres, type PostgresClientLike } from "../../drivers/postgres.ts";
+import { createSqlStoreHandle } from "./sql-session.ts";
+
+/**
+ * Two-slot pool. `reserve()` holds a slot until `release()`. Unreserved
+ * `BEGIN` occupies a slot until COMMIT on that same checkout.
+ */
+function createTinyPoolClient(size = 2): PostgresClientLike & {
+  readonly reserveCalls: { n: number };
+  readonly rootBegins: { n: number };
+} {
+  const slots = Array.from({ length: size }, () => ({ held: false }));
+  const reserveCalls = { n: 0 };
+  const rootBegins = { n: 0 };
+
+  function checkout(): { held: boolean } {
+    const idle = slots.find((slot) => !slot.held);
+    if (!idle) {
+      throw new Error("checkout timeout");
+    }
+    return idle;
+  }
+
+  function rowsFor(sql: string): Record<string, unknown>[] {
+    return /select/i.test(sql) && !/set_config/i.test(sql) ? [{ id: "a", owner: "alice" }] : [];
+  }
+
+  const client: PostgresClientLike & {
+    readonly reserveCalls: { n: number };
+    readonly rootBegins: { n: number };
+  } = {
+    reserveCalls,
+    rootBegins,
+    async reserve() {
+      reserveCalls.n += 1;
+      const slot = checkout();
+      slot.held = true;
+      return {
+        async unsafe(sql) {
+          return rowsFor(sql);
+        },
+        release() {
+          slot.held = false;
+        },
+      };
+    },
+    async unsafe(sql) {
+      const slot = checkout();
+      const head = sql.trim().split(/\s+/)[0]?.toUpperCase();
+      if (head === "BEGIN") {
+        rootBegins.n += 1;
+        slot.held = true;
+        return [];
+      }
+      if (head === "COMMIT" || head === "ROLLBACK") {
+        slot.held = false;
+        return [];
+      }
+      return rowsFor(sql);
+    },
+  };
+  return client;
+}
+
+describe("sql-session RLS stamp on pooled postgres", () => {
+  test("pins the stamp through reserve — no leaked root BEGIN", async () => {
+    const pool = createTinyPoolClient(2);
+    const connection = await connectPostgres({ client: pool, role: "primary" });
+    const handle = createSqlStoreHandle("sql:app", {
+      connection,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "off",
+      rls: { gate: "member", userId: "alice", scopes: ["member"] },
+    });
+
+    const [a, b] = await Promise.all([
+      handle.raw(`SELECT id, owner FROM notes`),
+      handle.raw(`SELECT id, owner FROM notes`),
+    ]);
+
+    expect(a).toEqual([{ id: "a", owner: "alice" }]);
+    expect(b).toEqual([{ id: "a", owner: "alice" }]);
+    expect(pool.reserveCalls.n).toBe(2);
+    expect(pool.rootBegins.n).toBe(0);
+  });
+
+  test("table browse SELECT pins through reserve like any other stamped query", async () => {
+    const pool = createTinyPoolClient(2);
+    const connection = await connectPostgres({ client: pool, role: "primary" });
+    const handle = createSqlStoreHandle("sql:app", {
+      connection,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "off",
+      rls: { gate: "member", userId: "alice", scopes: ["member"] },
+    });
+    const rows = await handle.raw(`SELECT * FROM "notes" LIMIT 50`);
+    expect(rows).toEqual([{ id: "a", owner: "alice" }]);
+    expect(pool.reserveCalls.n).toBe(1);
+    expect(pool.rootBegins.n).toBe(0);
+  });
+
+  test("standalone BEGIN on a 2-slot pool reproduces checkout timeout", async () => {
+    const pool = createTinyPoolClient(2);
+    await expect(pool.unsafe("BEGIN")).resolves.toEqual([]);
+    await expect(pool.unsafe("BEGIN")).resolves.toEqual([]);
+    await expect(pool.unsafe("SET LOCAL ROLE oke_app")).rejects.toThrow("checkout timeout");
+  });
+});

package/src/elements/store/sql-session.ts

@@ -7,6 +7,12 @@
 
 import type { DomainDdlMode } from "../../config/index.ts";
 import type { ClassificationMap, SqlConnection, SqlRow } from "../../drivers/types.ts";
+import {
+  buildRlsIdentityPreludeSql,
+  installOkeRlsHelpers,
+  RLS_CONTEXT_DRIVERS,
+  type RlsIdentity,
+} from "../../drivers/pg-rls.ts";
 import { throwOke } from "../../kernel/errors.ts";
 import { maskRows, tableFromSql } from "./classify.ts";
 import { isMissingDomainRelationError } from "./missing-relation.ts";
@@ -28,6 +34,45 @@ import {
 
 export type { WhereMap } from "./sql-condition.ts";
 
+/** Serialize stamp frames on a shared connection so concurrent identities cannot interleave. */
+const rlsStampTails = new WeakMap<SqlConnection, Promise<unknown>>();
+
+/**
+ * True when SQL must not enter an RLS identity frame (txn control or DDL).
+ *
+ * @param sql - Statement
+ */
+export function isRlsStampExemptSql(sql: string): boolean {
+  return /^\s*(begin|commit|rollback|create|alter|drop|truncate|grant|revoke|comment)\b/i.test(sql);
+}
+
+/**
+ * Run `fn` after any in-flight stamp on `connection` finishes.
+ *
+ * @param connection - Shared SQL connection
+ * @param fn - Stamp frame
+ */
+async function withRlsStampLock<T>(connection: SqlConnection, fn: () => Promise<T>): Promise<T> {
+  const prev = rlsStampTails.get(connection) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  rlsStampTails.set(
+    connection,
+    prev.then(
+      () => gate,
+      () => gate,
+    ),
+  );
+  await prev.catch(() => undefined);
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}
+
 /** Options for a SQL session. */
 export interface SqlSessionOptions {
   /** Open connection (already role-routed). */
@@ -44,6 +89,8 @@ export interface SqlSessionOptions {
    * and local+autoPush). Default `ensure` for backward-compatible tests.
    */
   readonly domainDdl?: DomainDdlMode;
+  /** Gate identity — stamps `oke.*` on postgres / pglite. */
+  readonly rls?: RlsIdentity;
 }
 
 /**
@@ -339,8 +386,9 @@ export function createSqlStoreHandle(
   ref: `sql:${string}`,
   options: SqlSessionOptions,
 ): SqlStoreHandle {
-  const { connection, classifications, revealPii } = options;
+  const { connection, classifications, revealPii, rls } = options;
   const domainDdl: DomainDdlMode = options.domainDdl ?? "ensure";
+  let helpersReady = false;
 
   function mask(rows: SqlRow[], table?: string): SqlRow[] {
     return maskRows(rows, { classifications, table, revealPii });
@@ -362,11 +410,41 @@ export function createSqlStoreHandle(
   }
 
   function query(sql: string, params: readonly unknown[] = []): Promise<SqlRow[]> {
-    return withSchemaGuard(() => connection.query(sql, params));
+    return withSchemaGuard(() => withRlsStamp((conn) => conn.query(sql, params), sql));
   }
 
   function exec(sql: string, params: readonly unknown[] = []): Promise<{ changes: number }> {
-    return withSchemaGuard(() => connection.exec(sql, params));
+    return withSchemaGuard(() => withRlsStamp((conn) => conn.exec(sql, params), sql));
+  }
+
+  async function withRlsStamp<T>(fn: (conn: SqlConnection) => Promise<T>, sql: string): Promise<T> {
+    if (!rls || !RLS_CONTEXT_DRIVERS.has(connection.driverId)) return fn(connection);
+    if (isRlsStampExemptSql(sql)) return fn(connection);
+    const run = (): Promise<T> => applyRlsStamp(fn);
+    // PGlite is one backend session — concurrent identities must not interleave.
+    // Pooled postgres pins each stamp via `transaction()` instead.
+    if (connection.driverId === "pglite") {
+      return withRlsStampLock(connection, run);
+    }
+    return run();
+  }
+
+  async function applyRlsStamp<T>(fn: (conn: SqlConnection) => Promise<T>): Promise<T> {
+    if (!rls) return fn(connection);
+    if (!helpersReady) {
+      await installOkeRlsHelpers((sql) => connection.exec(sql));
+      helpersReady = true;
+    }
+    const frame = async (tx: SqlConnection): Promise<T> => {
+      for (const stmt of buildRlsIdentityPreludeSql(rls)) {
+        await tx.exec(stmt.sql, stmt.params ?? []);
+      }
+      return fn(tx);
+    };
+    if (!connection.transaction) {
+      throw new Error("RLS stamp needs SqlConnection.transaction to pin SET LOCAL");
+    }
+    return connection.transaction(frame);
   }
 
   async function ensureFromMeta(table: TableHandle | unknown): Promise<void> {

package/src/elements/store/upsert-app.test.ts

@@ -45,7 +45,7 @@ describe("fx.store(db).upsert via app.fetch (real boot)", () => {
     const db = store.sql("app", { schema: { notes } });
 
     const seed = on(
-      http.post("/seed").gate.public,
+      http.post("/seed").public(),
       flow("notes.seed", {
         in: UpsertIn,
         out: UpsertOut,