chore: refine policy enforcement, demo scripts, and tooling

Update proxy policy hooks and enforcement tests, refresh the ecommerce
demo (compose file, setup script, schema, policies, seed), polish admin
UI forms, and extend CLAUDE.md guidance plus pre-commit and CI config.

Author: jumpbetweenrows

.claude/CLAUDE.md

@@ -71,6 +71,8 @@ Every feature plan MUST include a comprehensive test case inventory before imple
 
 **Test naming convention:** Group tests by category with descriptive names. Map security-relevant tests to vector numbers in `docs/security-vectors.md`.
 
+**Adding a new security vector:** When a new feature or bug fix touches access control, policy resolution, or data visibility, add (or update) an entry in `docs/security-vectors.md` using the standard schema defined at the top of that file. Section order is fixed: `**Vector**` → `**Attacks**` → `**Defense**` → `**Previously**` *(only if strengthening an earlier defense)* → `**Status**` *(only for unmitigated threats or accepted trade-offs)* → `**Tests**`. Every attack variant must either have a test back-reference (`— attack N`) in the `**Tests**` section or be explicitly marked under `**Status**`. Never use `**Bug**` as a section label — historical fix context goes in `**Previously**` in past tense. See the top of `docs/security-vectors.md` for the full schema description and `### 13` for a canonical example with multiple attack variants plus a `Previously` section.
+
 ### Security-First Thinking
 This is a data security product. Every feature that touches access control, policy resolution, or data visibility must be evaluated through a security lens:
 - **What can an attacker do?** — enumerate bypass vectors before building defenses

.githooks/pre-commit

@@ -22,3 +22,15 @@ echo "→ admin-ui typecheck"
 
 echo "→ admin-ui tests"
 (cd admin-ui && npm run test:run)
+
+# Only run docs-site checks if files under docs-site/ are staged AND the
+# docs-site deps are installed (first clone won't have them yet).
+if git diff --cached --name-only --diff-filter=ACMR | grep -q '^docs-site/'; then
+  if [ -d "docs-site/node_modules" ]; then
+    echo "→ docs-site vitepress build"
+    (cd docs-site && npm run build)
+  else
+    echo "→ docs-site has staged changes but node_modules is missing; skipping build check"
+    echo "  Run 'cd docs-site && npm ci' once to enable docs checks in the hook."
+  fi
+fi

.github/workflows/cicd.yml

@@ -44,6 +44,27 @@ jobs:
         run: npm run test:run
         working-directory: admin-ui
 
+  docs-site:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install docs-site dependencies
+        run: npm ci
+        working-directory: docs-site
+
+      - name: VitePress build
+        run: npm run build
+        working-directory: docs-site
+
   publish:
     needs: test
     if: startsWith(github.ref, 'refs/tags/v')

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **[Proxy] BREAKING: `ctx.query.tables` is now an array of objects, not strings** — decision functions with `evaluate_context = "query"` previously received `ctx.query.tables` as `string[]` (e.g. `["public.orders"]`). It is now `Array<{datasource, schema, table}>`, so decision function JS must access the fields explicitly. Bare references like `SELECT * FROM orders` now also resolve to the session's default schema (e.g. `public`) rather than an empty schema segment, so qualified and unqualified references produce identical entries.
+
+  Migration for any decision function that inspected `ctx.query.tables`:
+
+  ```js
+  // Before:
+  ctx.query.tables.includes("public.orders")
+  ctx.query.tables.some(t => t.startsWith("public."))
+
+  // After:
+  ctx.query.tables.some(t => t.schema === "public" && t.table === "orders")
+  ctx.query.tables.some(t => t.schema === "public")
+  ```
+
 ## [0.14.1] - 2026-04-09
 
 ### Changed

admin-ui/src/components/CatalogDiscoveryWizard.tsx

@@ -198,6 +198,15 @@ export function CatalogDiscoveryWizard({ datasourceId }: Props) {
   }
 
   async function runSaveCatalog() {
+    // TODO(rename-warning): if any entry in schemaAliases differs from the
+    // existing schema_alias on the already-persisted schema, surface the
+    // impact of the rename to the admin before saving — schema alias changes
+    // break SQL queries using the old alias, decision function JS matching on
+    // `ctx.query.tables[*].schema`, stored queries/dashboards, and audit logs
+    // tagged with the old alias. Policy *enforcement* continues to work
+    // because `matches_table` resolves aliases to upstream schema names via
+    // `df_to_upstream` at session build time. See `docs/permission-system.md`
+    // → "Rename fragility and label-based identifiers".
     setError(null)
     setProgress(null)
     setIsWorking(true)

admin-ui/src/components/DecisionFunctionModal.tsx

@@ -71,7 +71,10 @@ function buildCtxCompletions(evaluateContext: EvaluateContext, configStr: string
 
   if (evaluateContext === 'query') {
     items.push(
-      { label: 'ctx.query.tables', type: 'variable' as const, detail: 'string[]' },
+      { label: 'ctx.query.tables', type: 'variable' as const, detail: '{datasource, schema, table}[]' },
+      { label: 'ctx.query.tables[0].datasource', type: 'variable' as const, detail: 'string' },
+      { label: 'ctx.query.tables[0].schema', type: 'variable' as const, detail: 'string' },
+      { label: 'ctx.query.tables[0].table', type: 'variable' as const, detail: 'string' },
       { label: 'ctx.query.columns', type: 'variable' as const, detail: 'string[]' },
       { label: 'ctx.query.join_count', type: 'variable' as const, detail: 'number' },
       { label: 'ctx.query.has_aggregation', type: 'variable' as const, detail: 'boolean' },

admin-ui/src/components/PolicyForm.tsx

@@ -276,7 +276,7 @@ export function PolicyForm({ initial, onSubmit, submitLabel, isSubmitting, error
   const [attrDefs, setAttrDefs] = useState<AttributeDefinition[]>([])
   useEffect(() => {
     listAttributeDefinitions({ entity_type: 'user', page_size: 200 })
-      .then((res) => setAttrDefs(res.data))
+      .then((res) => setAttrDefs(res.data ?? []))
       .catch(() => {})
   }, [])
   const templateItems = useMemo(

admin-ui/src/pages/DataSourceEditPage.tsx

@@ -29,6 +29,14 @@ export function DataSourceEditPage() {
     is_active: boolean
     access_mode?: string
   }) {
+    // TODO(rename-warning): if values.name differs from ds.name, surface the
+    // impact of the rename to the admin before committing — datasource name
+    // changes break SQL 3-part references (`oldName.schema.table`), connection
+    // strings, decision function JS matching on `ctx.query.tables[*].datasource`
+    // or `ctx.session.datasource.name`, and audit log consumers keyed on the
+    // old name. Policy *enforcement* continues to work because policies are
+    // assigned by datasource_id. See `docs/permission-system.md` → "Rename
+    // fragility and label-based identifiers" for the full impact matrix.
     setIsSubmitting(true)
     try {
       await updateDataSource(dsId, {

admin-ui/vitest.config.ts

@@ -5,6 +5,17 @@ export default defineConfig({
   plugins: [react()],
   test: {
     environment: 'jsdom',
+    // Pin jsdom's document URL to a closed TCP port. Axios in our client
+    // uses baseURL: '/api/v1', which jsdom resolves against window.location.
+    // Vitest's default http://localhost:3000/ means any unmocked test call
+    // leaks to whatever happens to listen on :3000 (e.g. another vite dev
+    // server on the same machine), which returns HTML for any path and
+    // crashes components that try to .map()/.length the "response". Port 1
+    // is guaranteed closed in practice — axios gets connection-refused in
+    // ~1ms, the query enters error state, and defensive render paths kick in.
+    environmentOptions: {
+      jsdom: { url: 'http://localhost:1/' },
+    },
     globals: true,
     css: false,
     setupFiles: ['./src/test/setup.ts'],

docs/permission-system.md

@@ -488,6 +488,33 @@ function evaluate(ctx, config) {
 
 `time.now` is an ISO 8601 / RFC 3339 timestamp representing the **evaluation time** — the moment the context is built. For visibility-level functions this is when the connection context is computed; for query-level functions it is when the query is processed. This enables time-windowed decision functions (e.g., break-glass temporary access).
 
+#### `ctx.query.tables` — structured table references
+
+Each entry in `ctx.query.tables` is an object with three string fields:
+
+```js
+ctx.query.tables; // Array of { datasource, schema, table }
+```
+
+| Field | What it contains |
+|-------|------------------|
+| `datasource` | The BetweenRows datasource name the session is connected to (e.g. `"prod"`). Same value as `ctx.session.datasource.name`. |
+| `schema` | The schema alias the user referenced (or the upstream schema name if no alias is configured). For bare references like `FROM orders`, this is the session's default schema (e.g. `"public"`) — **never** an empty string. |
+| `table` | The table name as referenced in the SQL. |
+
+A bare reference `SELECT * FROM orders JOIN users` and a qualified reference `SELECT * FROM public.orders JOIN public.users` produce **identical** `ctx.query.tables` arrays, so decision function logic doesn't need to handle both forms:
+
+```js
+// Matches regardless of whether the user wrote bare `orders` or `public.orders`
+const touchesOrders = ctx.query.tables.some(
+  t => t.schema === "public" && t.table === "orders"
+);
+```
+
+System tables (`pg_catalog.*`, `information_schema.*`) are filtered out of `ctx.query.tables` entirely — decision functions never see them.
+
+**Identifier stability**: `datasource` and `schema` are **user-facing labels** that admins can rename (see "Rename fragility and label-based identifiers" below). If an admin renames the `prod` datasource to `production`, decision functions that hardcoded `t.datasource === "prod"` will silently stop matching. Prefer matching on `table` (which is stable with the upstream name) plus `schema` (which is generally stable unless an alias is reconfigured) for rules you want to survive renames. A future rename-warning UX will surface the impact of renames before admins commit them.
+
 Custom user attributes are flattened as first-class fields on the `user` object with correctly typed values (string/number/boolean/array) — e.g., `ctx.session.user.region`, not `ctx.session.user.attributes.region`. This matches the flat `{user.KEY}` namespace used in template variables. In the API, the same attributes are nested under `attributes` (see [Namespace design](#namespace-design-flat-in-expressions-nested-in-api)). List attributes appear as JSON arrays of strings. Built-in fields (`id`, `username`, `roles`) always take priority. See [User Attributes (ABAC)](#user-attributes-abac) for details.
 
 **Visibility-level enforcement**: `column_deny`, `table_deny`, and `column_allow` policies are enforced at connect time (visibility level) by removing columns/tables from the per-user schema. Decision functions on these policy types are evaluated at visibility time when `evaluate_context = "session"`. If the decision function returns `fire: false`, the policy is skipped and the column/table remains visible. For `evaluate_context = "query"`, the policy's visibility effect is skipped entirely (deferred to query time), since query metadata is not available at connect time — the column/table stays visible in the schema and the decision function runs at query time as normal.
@@ -1307,4 +1334,27 @@ Attach this to a `table_deny` policy targeting `executive_comp` — executives s
 | Tiered masking by clearance | Nested `CASE WHEN` in `column_mask` | `CASE WHEN {user.clearance} >= 5 THEN val WHEN ... END` |
 | Mask using row data + user attributes | `CASE WHEN` referencing both | `CASE WHEN region = {user.region} THEN val ELSE ... END` |
 | Conditional deny/allow | Decision function | `{ fire: ctx.session.user.team !== 'x' }` |
+
+## Rename fragility and label-based identifiers
+
+BetweenRows uses **user-facing labels** for identifiers everywhere users touch the system: datasource names, schema aliases, policy names, and decision function contexts. This is intentional — stable IDs (UUIDs) would be unusable as SQL identifiers and would force admins to hand-write UUIDs in policy targets.
+
+The tradeoff is that **renames are breaking changes** for anything that references the old label. Three rename operations matter:
+
+| Rename | What breaks | What keeps working |
+|--------|-------------|--------------------|
+| **Datasource name** (e.g. `prod` → `production`) | Connection strings (`dbname=prod`); 3-part SQL references (`prod.public.orders`); `ctx.session.datasource.name` checks; `ctx.query.tables[*].datasource` checks in decision function JS; audit log rows tagged with the old name | Policy enforcement for in-flight queries: policies are assigned by `datasource.id` (UUID), not name, so they continue to match after the rename |
+| **Schema alias** (e.g. `public` → `main`) | SQL queries using the old alias; `ctx.query.tables[*].schema` checks; `{user.KEY}` expressions that embed the alias; dashboards and stored queries | Policy target matching: `TargetEntry::matches_table` resolves the new alias to the upstream schema name via `df_to_upstream` at session build time, and policy targets store upstream names — so enforcement is stable across alias renames |
+| **Upstream schema or database rename** (performed in the actual Postgres, not BR) | Everything that references it — catalog discovery must be re-run, and `df_to_upstream` entries rebuilt | Policies need to be retargeted manually |
+
+**Guidance for decision function authors**: prefer matching on `t.table` (stable with upstream) plus `t.schema` (usually stable unless an alias is reconfigured) over `t.datasource`. If a rule must survive datasource renames, gate it on `ctx.session.user.roles` or attributes, not on datasource identity.
+
+**Guidance for admins**: when renaming a datasource or schema alias, audit existing:
+
+1. Decision function JS for references to the old name
+2. Stored queries, dashboards, and SQL snippets in external tools (BR cannot see these)
+3. Connection strings in deployed applications
+4. Audit logs and any downstream log aggregators keyed on the old name
+
+A future rename-warning feature will surface a list of affected entities before the rename commits. Until then, renames should be treated as a coordinated operation, not a casual UI edit. Policy *enforcement* (the security layer) is the one thing that stays correct across renames automatically.
 | Combine multiple filters | Separate policies (AND-combined) | Two `row_filter` policies on same table |