security: document SECURITY DEFINER interaction with df.start() and add start_use_session_user GUC

[Copilot]

df.start() captures identity via GetUserId() (current_user). Inside a SECURITY DEFINER function, current_user is the function owner, so any SQL in the fut argument executes with the definer's privileges — even when supplied by an unprivileged caller.

Changes

src/lib.rs + src/types.rs

• New GUC pg_durable.start_use_session_user (bool, default off, Suset/superuser-only, changeable at runtime)
• start_use_session_user() helper reads the GUC

src/dsl.rs

• df.start() now calls GetSessionUserId() when the GUC is on, GetUserId() otherwise — all downstream identity validation logic is unchanged

USER_GUIDE.md

• Rewrote "How Identity Is Captured" to accurately reflect the single-OID capture model
• New ⚠️ SECURITY DEFINER Warning subsection: dangerous pattern example, root cause, and three mitigations (avoid the pattern / enable the GUC / use SECURITY INVOKER)
• Added item Refactor DSL to use nested JSON graph construction #5 to "Security Best Practices" cross-referencing the new warning

tests/e2e/sql/13_user_isolation.sql

• Test 6c: with start_use_session_user = on, calling the same SECURITY DEFINER wrapper as iso_alice captures session_user = iso_alice (not the definer postgres), and the SQL node fails because alice has no access to the superuser-only table

Usage

-- Prevent SECURITY DEFINER wrappers from escalating identity (set in postgresql.conf
-- or ALTER DATABASE SET; superusers can also SET per-session):
SET pg_durable.start_use_session_user = on;

-- Now even inside a SECURITY DEFINER function, df.start() records session_user:
CREATE FUNCTION run_report(q TEXT) RETURNS TEXT
LANGUAGE SQL SECURITY DEFINER AS $$
    SELECT df.start(df.sql(q), 'report');  -- captures caller's login role, not owner
$$;

Note: Enabling this GUC changes identity capture for all df.start() calls in scope. If your application uses SET ROLE to submit workflows under a group role, the captured identity will revert to the session login role instead.