okengine 0.17.2 → 0.18.4

package/src/drivers/oauth-types.ts

@@ -0,0 +1,159 @@
+/**
+ * Protocol-named OAuth client driver contracts.
+ *
+ * Two provider shapes (locked design):
+ * - `oidc` — discovery + JWKS-verified ID tokens (Google, Apple, Microsoft)
+ * - `oauth2` — code → access token → userinfo-equivalent, normalized into the
+ *   same {@link OAuthAssertion} ("OIDC wrapper" pattern; GitHub, Discord, X,
+ *   Facebook, Figma)
+ *
+ * Every driver enforces Authorization Code + PKCE (S256). Implicit and ROPC
+ * grants are never implemented.
+ */
+
+/** Supported social providers. */
+export type OAuthDriverId =
+  | "apple"
+  | "discord"
+  | "facebook"
+  | "figma"
+  | "github"
+  | "google"
+  | "microsoft"
+  | "x";
+
+/** Token payload returned by a provider's token endpoint. */
+export interface OAuthTokenSet {
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  /** Epoch-ms expiry of the access token when the provider reports one. */
+  readonly expiresAt?: number;
+  readonly scopes?: readonly string[];
+  /** Raw OIDC ID token (base64url JWT) — `oidc` drivers only. */
+  readonly idToken?: string;
+  /** Full provider response (secrets included) — never logged. */
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/** Input to {@link OAuthDriver.buildAuthorizeUrl}. */
+export interface OAuthAuthorizeInput {
+  readonly clientId: string;
+  /**
+   * EXACT redirect URI string registered at the provider. Never derived from
+   * the incoming request — RFC 9700 requires byte-exact comparison.
+   */
+  readonly redirectUri: string;
+  readonly scopes: readonly string[];
+  readonly state: string;
+  /** Base64url(SHA-256(code_verifier)) — PKCE S256, mandatory. */
+  readonly codeChallenge: string;
+  /** OIDC nonce echoed in the ID token. */
+  readonly nonce?: string;
+}
+
+/** Result of {@link OAuthDriver.buildAuthorizeUrl}. */
+export interface OAuthAuthorizeResult {
+  /** Provider authorization endpoint URL incl. all query parameters. */
+  readonly url: string;
+}
+
+/** Input to {@link OAuthDriver.exchangeCode}. */
+export interface OAuthExchangeInput {
+  readonly clientId: string;
+  /** Confidential-client secret (revealed from Vault at the boundary). */
+  readonly clientSecret?: string;
+  /**
+   * Apple only — signs a fresh ES256 client-secret JWT per exchange.
+   * Wins over {@link clientSecret} when set.
+   */
+  readonly clientSecretJwt?: () => Promise<string>;
+  /** Exact redirect URI stored on the flow record at start. */
+  readonly redirectUri: string;
+  readonly code: string;
+  readonly codeVerifier: string;
+  /** Injectable fetch (tests). Defaults to `globalThis.fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Injectable clock. */
+  readonly now?: () => number;
+}
+
+/** Result of {@link OAuthDriver.exchangeCode}. */
+export interface OAuthExchangeResult {
+  readonly tokens: OAuthTokenSet;
+}
+
+/** Input to {@link OAuthDriver.resolveAssertion}. */
+export interface OAuthAssertionInput {
+  readonly tokens: OAuthTokenSet;
+  /**
+   * Issuer the flow was initiated against (stored on the flow record at
+   * start). Assertions whose issuer differs are mix-up attacks — rejected.
+   */
+  readonly expectedIssuer: string;
+  /** Expected ID token / client audience (= clientId). */
+  readonly expectedAudience: string;
+  /** Expected OIDC nonce from the flow record. */
+  readonly expectedNonce?: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly now?: () => number;
+}
+
+/**
+ * Uniform internal identity assertion — the "OIDC wrapper" every driver
+ * produces regardless of provider shape.
+ *
+ * `emailVerified` follows the per-provider trust matrix and defaults to
+ * `false`; it is `true` only on an explicit provider attestation.
+ */
+export interface OAuthAssertion {
+  /** Stable provider-scoped subject (`sub` / provider user id). */
+  readonly subject: string;
+  /** Verified issuer — equals {@link OAuthAssertionInput.expectedIssuer}. */
+  readonly issuer: string;
+  readonly email?: string;
+  readonly emailVerified: boolean;
+  readonly name?: string;
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * One social-login driver. Small, focused modules behind this shared
+ * interface — never one generalized function branching on provider name.
+ */
+export interface OAuthDriver {
+  readonly id: OAuthDriverId;
+  /** `oidc` (discovery + ID token) or `oauth2` (userinfo equivalent). */
+  readonly kind: "oidc" | "oauth2";
+  /**
+   * Stable issuer identifier bound to the flow record at start and checked
+   * against the assertion on callback — the mix-up defense anchor
+   * (RFC 9700 §4.4 / RFC 9207).
+   */
+  readonly authorizationServerId: string;
+  /** Build the provider authorize URL (Authorization Code + PKCE S256). */
+  buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult;
+  /** Exchange `code` for tokens using the exact stored redirect URI. */
+  exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult>;
+  /**
+   * Normalize tokens into an {@link OAuthAssertion}: OIDC drivers verify the
+   * ID token (sig, iss, aud, nonce, exp); `oauth2` drivers call their
+   * userinfo-equivalent endpoint.
+   */
+  resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion>;
+}
+
+/** Thrown on any OAuth protocol failure (exchange, assertion, mix-up). */
+export class OAuthProtocolError extends Error {
+  /** Machine-readable failure reason (safe to surface as `AuthFailed.reason`). */
+  readonly reason: string;
+
+  /**
+   * @param reason - Stable failure slug (e.g. `issuer_mismatch`)
+   * @param message - Human context (logged, never returned to clients)
+   */
+  constructor(reason: string, message: string) {
+    super(message);
+    this.name = "OAuthProtocolError";
+    this.reason = reason;
+  }
+}

package/src/drivers/oauth-x.ts

@@ -0,0 +1,77 @@
+/**
+ * `x` OAuth2 driver (Authorization Code with PKCE — X has no OIDC).
+ * Profile: `GET /2/users/me?user.fields=confirmed_email`.
+ *
+ * Trust: `emailVerified` is **always false** — `confirmed_email` is an app
+ * permission gate, not a verification attestation (locked decision 5). Email
+ * may be absent without the `users.email` scope + elevated app access.
+ */
+
+import {
+  type OAuthAssertion,
+  type OAuthAssertionInput,
+  type OAuthAuthorizeInput,
+  type OAuthAuthorizeResult,
+  type OAuthDriver,
+  type OAuthExchangeInput,
+  type OAuthExchangeResult,
+} from "./oauth-types.ts";
+import { buildAuthorizeQuery } from "./oauth-shared.ts";
+import { fetchProviderJson, resolveOauth2Assertion } from "./oauth2-common.ts";
+import { postTokenRequest } from "./oauth2-token.ts";
+
+const AUTHORIZATION_SERVER_ID = "https://x.com";
+
+/** Default X scopes. */
+export const X_DEFAULT_SCOPES = ["users.read", "tweet.read"] as const;
+
+/**
+ * Open the X driver.
+ *
+ * @param options - Optional scope override / injectable fetch
+ */
+export function openOAuthX(
+  options: { readonly scopes?: readonly string[]; readonly fetch?: typeof globalThis.fetch } = {},
+): OAuthDriver {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  return {
+    id: "x",
+    kind: "oauth2",
+    authorizationServerId: AUTHORIZATION_SERVER_ID,
+    buildAuthorizeUrl(input: OAuthAuthorizeInput): OAuthAuthorizeResult {
+      return { url: buildAuthorizeQuery("https://x.com/i/oauth2/authorize", input) };
+    },
+    async exchangeCode(input: OAuthExchangeInput): Promise<OAuthExchangeResult> {
+      // X is a public client — no client_secret on the token call.
+      return {
+        tokens: await postTokenRequest({
+          tokenEndpoint: "https://api.x.com/2/oauth2/token",
+          input,
+        }),
+      };
+    },
+    async resolveAssertion(input: OAuthAssertionInput): Promise<OAuthAssertion> {
+      return resolveOauth2Assertion(input, async (accessToken) => {
+        const res = await fetchProviderJson(
+          "https://api.x.com/2/users/me?user.fields=id,name,username,confirmed_email",
+          accessToken,
+          fetchFn,
+          "x",
+        );
+        const data = res["data"];
+        if (data === null || typeof data !== "object") throw new Error("x: profile missing data");
+        const user = data as Record<string, unknown>;
+        const subject = typeof user["id"] === "string" ? user["id"] : undefined;
+        if (subject === undefined) throw new Error("x: profile missing id");
+        return {
+          providerId: "x",
+          subject,
+          ...(user["confirmed_email"] !== undefined ? { email: user["confirmed_email"] } : {}),
+          // Locked trust decision: never verified via X.
+          name: typeof user["name"] === "string" ? user["name"] : undefined,
+          raw: user,
+        };
+      });
+    },
+  };
+}

package/src/drivers/oauth2-common.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared OAuth 2.0-only driver machinery: the "OIDC wrapper" — userinfo-
+ * equivalent fetches normalized into an {@link OAuthAssertion}.
+ *
+ * These providers have no `iss` on their identity surface; the mix-up anchor
+ * is the flow record's `authorizationServerId`, checked by the plugin before
+ * any driver call (RFC 9700 §4.4 alternate: distinct callback paths).
+ */
+
+import type { OAuthAssertion, OAuthAssertionInput } from "./oauth-types.ts";
+import { normalizeEmail } from "./oauth-shared.ts";
+
+/**
+ * Provider-agnostic profile fields a driver resolves before normalization.
+ * `verified` carries only explicit provider attestations (GitHub primary,
+ * Discord); Facebook / X / Figma omit it entirely → always unverified.
+ */
+export interface OAuth2Profile {
+  readonly providerId: string;
+  readonly subject: string;
+  readonly email?: unknown;
+  readonly verified?: unknown;
+  readonly name?: unknown;
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Fetch a provider JSON endpoint with bearer auth.
+ *
+ * @param url - Endpoint
+ * @param accessToken - Bearer token
+ * @param fetchFn - Injectable fetch
+ * @param provider - Driver id for error context
+ */
+export async function fetchProviderJson(
+  url: string,
+  accessToken: string,
+  fetchFn: typeof globalThis.fetch,
+  provider: string,
+): Promise<Record<string, unknown>> {
+  const res = await fetchFn(url, {
+    headers: {
+      authorization: `Bearer ${accessToken}`,
+      accept: "application/json",
+      // GitHub v3 convention — avoids XML fallbacks.
+      "user-agent": "okengine-oauth",
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`${provider}: profile request failed with HTTP ${res.status}`);
+  }
+  return (await res.json()) as Record<string, unknown>;
+}
+
+/** Trust matrix: verified only on an explicit boolean/string `true`. */
+function trustVerified(verified: unknown): boolean {
+  if (typeof verified === "boolean") return verified;
+  if (typeof verified === "string") return verified === "true";
+  return false;
+}
+
+/**
+ * Build an {@link OAuthAssertion} from resolved provider fields.
+ *
+ * @param options - Profile fields plus the pinned issuer
+ */
+export function oauth2Assertion(
+  options: OAuth2Profile & { readonly issuer: string },
+): OAuthAssertion {
+  const email = normalizeEmail(options.email);
+  const name =
+    typeof options.name === "string" && options.name.length > 0 ? options.name : undefined;
+  return {
+    subject: options.subject,
+    issuer: options.issuer,
+    ...(email !== undefined ? { email } : {}),
+    emailVerified: trustVerified(options.verified),
+    ...(name !== undefined ? { name } : {}),
+    raw: { ...options.raw, provider: options.providerId },
+  };
+}
+
+/**
+ * Standard resolveAssertion shape for OAuth2 drivers.
+ *
+ * @param input - Assertion inputs
+ * @param resolve - Profile resolver receiving the access token
+ */
+export async function resolveOauth2Assertion(
+  input: OAuthAssertionInput,
+  resolve: (accessToken: string) => Promise<OAuth2Profile>,
+): Promise<OAuthAssertion> {
+  const profile = await resolve(input.tokens.accessToken);
+  return oauth2Assertion({ ...profile, issuer: input.expectedIssuer });
+}

package/src/drivers/oauth2-token.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared token-exchange helper for OAuth 2.0-only drivers.
+ * (Split from oauth2-common to keep profile logic separate from transport.)
+ */
+
+import { OAuthProtocolError, type OAuthTokenSet } from "./oauth-types.ts";
+import type { OAuthExchangeInput } from "./oauth-types.ts";
+
+/**
+ * POST `code` (+ PKCE verifier) to a provider token endpoint and normalize
+ * the response. Providers without client auth (PKCE public clients) omit the
+ * secret automatically when undefined.
+ *
+ * @param options - Endpoint + exchange inputs
+ */
+export async function postTokenRequest(options: {
+  readonly tokenEndpoint: string;
+  readonly input: OAuthExchangeInput;
+}): Promise<OAuthTokenSet> {
+  const { input } = options;
+  const params = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: input.code,
+    redirect_uri: input.redirectUri,
+    client_id: input.clientId,
+    code_verifier: input.codeVerifier,
+  });
+  if (input.clientSecret !== undefined) params.set("client_secret", input.clientSecret);
+  const fetchFn = input.fetch ?? globalThis.fetch;
+  const res = await fetchFn(options.tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+      // X rejects JSON bodies; GitHub accepts both but form is universal.
+      "user-agent": "okengine-oauth",
+    },
+    body: params.toString(),
+  });
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!res.ok || typeof body["access_token"] !== "string") {
+    throw new OAuthProtocolError(
+      "exchange_failed",
+      `${options.tokenEndpoint} returned HTTP ${res.status}: ${String(body["error"] ?? "unknown")}`,
+    );
+  }
+  const expiresIn = body["expires_in"];
+  return {
+    accessToken: body["access_token"],
+    ...(typeof body["refresh_token"] === "string"
+      ? { refreshToken: body["refresh_token"] as string }
+      : {}),
+    ...(typeof expiresIn === "number"
+      ? { expiresAt: Math.floor(Date.now() / 1000 + expiresIn * 1000) }
+      : {}),
+    ...(typeof body["scope"] === "string"
+      ? { scopes: (body["scope"] as string).split(/\s+/).filter((s) => s.length > 0) }
+      : {}),
+    raw: body,
+  };
+}

package/src/drivers/pg-rls-row-passes.ts

@@ -0,0 +1,251 @@
+/**
+ * `oke.row_passes_policies` — synthetic-row RLS replay for CDC live queries.
+ *
+ * When a table row changes (CDC event), live-query fan-out must decide per
+ * subscriber whether the OLD version of the row was visible (`beforeVisible`)
+ * without heap access — after an UPDATE the heap holds only the after-image,
+ * after a DELETE nothing remains. The subscriber's stamped connection
+ * (`SET LOCAL ROLE oke_app` + `oke.*` GUCs) evaluates policies natively for
+ * heap rows; this helper gives the SAME verdict for a JSONB payload by
+ * replaying expressions straight from `pg_policies`.
+ *
+ * Parity contract (src/elements/store/rls-row-passes-policies.parity.test.ts):
+ *   replay(table, rowJson, "SELECT") === native stamped `WHERE pk = …` verdict
+ * across every shipped policy family (owner / tenant / gate / scope) and their
+ * real compositions, plus WITH CHECK probes via native INSERT attempts.
+ *
+ * Expression rewriting (inside the SQL function, per policy, per call):
+ * 1. Bare column tokens (resolved from `pg_attribute` of the SAME table) are
+ *    first wrapped in a placeholder `<<col>>`, then placeholders are
+ *    substituted with `(row_data->>'col')` once per column. Two-phase keeps
+ *    a single regexp_replace pass idempotent — a direct wrap re-matches on
+ *    every pass ((row_data->>'col')'s tail still sits between valid word
+ *    boundaries) and the loop never stabilizes.
+ * 2. The replacement string is DOLLAR-QUOTED (`$re$\1<<\2>>\3$re$`), never
+ *    E''-quoted: plpgsql folds `E'\1'` at body-compile time into chr(1),
+ *    silently corrupting backreferences.
+ * 3. `<`/`>` are excluded from both boundary classes so `<<col>>` cannot
+ *    re-match; single-quoted literals are protected because `'` is excluded
+ *    from boundaries too — `'owner'` never trips a column named `owner`.
+ * 4. `oke.*` helpers survive: their segments follow a `.` (excluded left
+ *    boundary). pg_policies stores them qualification-stripped
+ *    (`"user"()`); `"user"` is not a column token so it passes through and
+ *    resolves via search_path to oke.user() exactly as it does natively.
+ * 5. Keyword-shaped tokens are skipped; placeholder substitution uses plain
+ *    replace() so `id` never corrupts an already-substituted accessor.
+ *
+ * Semantics mirror native RLS:
+ * - `TO <role>` applicability: a policy applies only when the current user is
+ *   a member of one of its roles (`public`/`current_user` always; membership
+ *   via `pg_has_role`). The stamp runs as `oke_app`, so internal policies
+ *   granted to non-member roles are invisible to it natively — the replay
+ *   skips them identically (TO-role regression gate: F4-style cases).
+ * - `ALL` policies apply to every command; others match their own.
+ * - Clause selection per command mirrors the native backend:
+ *   SELECT/DELETE evaluate USING (qual); INSERT evaluates WITH CHECK only;
+ *   UPDATE must satisfy both (missing clause falls back to its sibling).
+ * - PERMISSIVE OR together, RESTRICTIVE AND; zero applicable policies on an
+ *   RLS-enabled table denies everything.
+ */
+
+/** One statement per exec — drivers reject multi-command batches on `query`. */
+export const ROW_PASSES_POLICIES_STATEMENTS: readonly string[] = [
+  String.raw`CREATE OR REPLACE FUNCTION oke.pol_applicable_to_role(
+  p_roles text[]
+) RETURNS boolean
+LANGUAGE sql STABLE AS $fn$
+  SELECT EXISTS (
+    SELECT 1
+      FROM unnest(p_roles) AS r(role)
+     WHERE r.role = 'public'
+        OR r.role = 'current_user'
+        OR r.role = 'session_user'
+        OR pg_has_role(current_user, r.role, 'MEMBER')
+  )
+$fn$`,
+  String.raw`CREATE OR REPLACE FUNCTION oke.row_passes_policies(
+  p_table text,
+  p_row jsonb,
+  p_command text
+) RETURNS boolean
+LANGUAGE plpgsql STABLE AS $fn$
+DECLARE
+  v_oid oid;
+  v_rls boolean := false;
+  pol record;
+  col record;
+  expr text;
+  next_text text;
+  n int;
+  acc text;
+  verdict boolean;
+  permissive_pass boolean := false;
+  has_permissive boolean := false;
+  restrictive_pass boolean := true;
+  has_restrictive boolean := false;
+BEGIN
+  SELECT c.oid, c.relrowsecurity INTO v_oid, v_rls
+    FROM pg_class c
+    JOIN pg_namespace nsp ON nsp.oid = c.relnamespace
+   WHERE c.relname = split_part(p_table, '.', 2)
+      OR c.relname = p_table
+   ORDER BY (nsp.nspname = 'public') DESC
+   LIMIT 1;
+
+  IF v_oid IS NULL OR NOT COALESCE(v_rls, false) THEN
+    RETURN true; -- unknown table or RLS off: everything visible (native parity)
+  END IF;
+
+  FOR pol IN
+    SELECT policyname, permissive, cmd, roles, qual, with_check
+      FROM pg_policies
+     WHERE tablename = split_part(p_table, '.', 2)
+        OR tablename = p_table
+  LOOP
+    -- Native TO-role semantics: a policy only applies when the current user is
+    -- a member of (one of) its roles. oke_app (the stamp role) is not normally
+    -- a member of custom policy roles, so such policies must be skipped —
+    -- otherwise an internal TO-restricted PERMISSIVE policy would wrongly widen
+    -- per-user visibility through the replay path.
+    IF NOT pol_applicable_to_role(pol.roles) THEN
+      CONTINUE;
+    END IF;
+
+    IF pol.cmd <> 'ALL' AND upper(p_command) <> pol.cmd THEN
+      CONTINUE;
+    END IF;
+
+    -- Command-clause selection mirrors each native command's evaluation:
+    --   SELECT/DELETE -> USING (qual) only
+    --   UPDATE        -> USING + WITH CHECK must both pass (native treats a
+    --                    missing clause as "same as the other")
+    --   INSERT        -> WITH CHECK only (qual does not gate new rows)
+    -- Zero applicable policies on an RLS-enabled table still denies all.
+    expr := CASE
+      WHEN upper(p_command) = 'INSERT' THEN COALESCE(pol.with_check, pol.qual)
+      ELSE COALESCE(pol.qual, pol.with_check)
+    END;
+
+    CONTINUE WHEN expr IS NULL;
+
+    FOR col IN
+      SELECT a.attname AS name
+        FROM pg_attribute a
+       WHERE a.attrelid = v_oid
+         AND a.attnum > 0
+         AND NOT a.attisdropped
+       ORDER BY a.attnum
+    LOOP
+      IF lower(col.name) IN (
+        'and','or','not','is','in','like','ilike','between','exists',
+        'case','when','then','else','end','true','false','null'
+      ) THEN
+        CONTINUE;
+      END IF;
+
+      -- Phase 1: wrap bare tokens as <<col>>. '<'/'>' sit outside the word
+      -- boundary classes, so the substituted form can never re-match and the
+      -- stabilization pass count is bounded by pathological overlaps only.
+      n := 0;
+      LOOP
+        n := n + 1;
+        IF n > 100 THEN
+          RAISE EXCEPTION 'row_passes_policies rewrite did not stabilize (%)', pol.policyname;
+        END IF;
+        next_text := replace(
+          regexp_replace(
+            expr,
+            '(^|[^A-Za-z0-9_''.<>])(' || col.name || ')($|[^A-Za-z0-9''<>])',
+            $re$\1<<\2>>\3$re$,
+            'g'
+          ),
+          chr(1) || '<<' || col.name || '>>' || chr(1),
+          '<<' || col.name || '>>'
+        );
+        EXIT WHEN next_text = expr;
+        expr := next_text;
+      END LOOP;
+
+      -- Phase 2: placeholders -> jsonb accessor (plain replace, order-safe).
+      acc := '(row_data->>''' || col.name || ''')';
+      expr := replace(expr, '<<' || col.name || '>>', acc);
+    END LOOP;
+
+    BEGIN
+      EXECUTE format('SELECT (%s) FROM (SELECT %L::jsonb AS row_data) AS t',
+                     expr, p_row::text) INTO verdict;
+    EXCEPTION WHEN OTHERS THEN
+      RAISE EXCEPTION 'row_passes_policies replay failed (%): %',
+        pol.policyname, SQLERRM;
+    END;
+
+    IF pol.permissive = 'PERMISSIVE' THEN
+      has_permissive := true;
+      IF verdict THEN permissive_pass := true; END IF;
+    ELSE
+      has_restrictive := true;
+      IF NOT verdict THEN restrictive_pass := false; END IF;
+    END IF;
+  END LOOP;
+
+  IF NOT has_permissive AND NOT has_restrictive THEN
+    RETURN false; -- RLS enabled, zero applicable policies: Postgres denies all
+  END IF;
+  RETURN (NOT has_restrictive OR restrictive_pass)
+     AND (NOT has_permissive OR permissive_pass);
+END
+$fn$`,
+];
+
+/**
+ * Probe for one replay evaluation.
+ *
+ * Prefer `sql`/`params` with drivers that bind JSON as an explicit type;
+ * Bun.SQL binds JS strings as unknown, so `$2::jsonb` yields a jsonb
+ * string scalar and `->>` lookups return NULL (live-PG parity failure).
+ * {@link buildInlineRowPassesSql} inlines the image safely instead.
+ *
+ * @param table - Table (bare name or `schema.table`)
+ * @param row - Synthetic row image (JSON-serializable)
+ * @param command - Command context (`SELECT` = visibility)
+ */
+export interface RowPassesProbe {
+  readonly sql: string;
+  readonly params: [string, string, string];
+}
+
+/** Escape a value for inline SQL literal embedding. */
+function escapeSqlLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+/**
+ * Inline-literal probe SQL — portable across pg drivers regardless of how
+ * each binds JS strings. Row payload and table name are escaped; command
+ * comes from a closed union.
+ *
+ * @param table - Table (bare name or `schema.table`)
+ * @param row - Synthetic row image
+ * @param command - Command context
+ */
+export function buildInlineRowPassesSql(
+  table: string,
+  row: Readonly<Record<string, unknown>>,
+  command: "ALL" | "SELECT" | "INSERT" | "UPDATE" | "DELETE" = "SELECT",
+): string {
+  const tableArg = escapeSqlLiteral(table);
+  const rowArg = `${escapeSqlLiteral(JSON.stringify(row))}::jsonb`;
+  return `SELECT oke.row_passes_policies(${tableArg}, ${rowArg}, ${escapeSqlLiteral(command)}) AS ok`;
+}
+
+/** Build a single replay probe (runs under the caller's RLS stamp). */
+export function buildRowPassesProbe(
+  table: string,
+  row: Readonly<Record<string, unknown>>,
+  command: "ALL" | "SELECT" | "INSERT" | "UPDATE" | "DELETE" = "SELECT",
+): RowPassesProbe {
+  return {
+    sql: "SELECT oke.row_passes_policies(?, ?, ?) AS ok",
+    params: [table, JSON.stringify(row), command],
+  };
+}

package/src/drivers/pg-rls.ts

@@ -482,3 +482,5 @@ export function buildRlsIdentityPreludeSql(identity: RlsIdentity): readonly RlsP
     },
   ];
 }
+
+export { buildRowPassesProbe, ROW_PASSES_POLICIES_STATEMENTS } from "./pg-rls-row-passes.ts";