point-topic-access 0.1.0__py3-none-any.whl

point_topic_access-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: point-topic-access
+Version: 0.1.0
+Summary: Shared permission -> ClickHouse access-control logic for Point Topic apps (claims, JWT verification, geo filter composer, per-org provisioning)
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: clickhouse-connect>=0.8.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pymongo>=4.10.0
+Requires-Dist: python-jose>=3.3.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=44.0.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pt-access — shared permission → ClickHouse access-control logic
+
+One place for the permission pipeline every Point Topic data app needs. Ported from the
+production-proven `point-topic-mcp` implementation (issues #100/#104/#105) so the MCP
+server, the ontology web app (`onto-app-new`) and future consumers cannot drift.
+
+> Full design context: [`HANDOFF.md`](HANDOFF.md). Tracked by
+> [onto-app-new#25](https://github.com/Point-Topic/onto-app-new/issues/25)
+> (Auth0 login + per-org dataset/geo permissions).
+
+## The pipeline
+
+```
+JWT claims ──► policy spec ──► SQL predicate ──► ClickHouse DDL
+(what you   (normalised    (composer:      (provisioning:
+ have)       dataset +      escaping,       role, grants,
+             filter rows)   containment,    row policies,
+                            OR-grouping)    settings profile)
+```
+
+Identity comes from the shared sub-site Auth0 tenant (`point-topic.eu.auth0.com`). The
+Post-Login Action stamps `pt_org_id` and `products[]` (`[{name, permissions}]`, scalar
+values only). **Geo filters are never in the token** — list values would bloat tokens
+past proxy header limits (documented decision in the Action's own code) — they are read
+**fresh from sub-site MongoDB** (`organisations.productPermissions.<ds> = {field: string[]}`)
+on every login/session, then converted to ClickHouse row policies.
+
+## Modules
+
+| Module | What | Ported from |
+|---|---|---|
+| `claims.py` | `get_org_id`, `get_held_products`, `is_pt_admin`, `has_data_source_access`, `get_product_role` | MCP `auth/middleware.py` (pure parts) |
+| `jwt.py` | `Auth0TokenVerifier` — JWKS cache, RS256, issuer/audience/exp checks | MCP `auth/auth0_helpers.py` (FastMCP wrapper stays in the MCP) |
+| `composer.py` | `compose_sql_filter` / `compose_geo_predicate` — sub-site permission values → per-dataset SQL disjunction | MCP `core/sql_filter_composer.py` (verbatim, live-verified SQL shapes) |
+| `provisioning.py` | `fetch_org_datasets` (sub-site Mongo read) + `resolve_org_config` + `provision_org_role` / `provision_org_on_login` (ClickHouse DDL, serialisation lock) | MCP `core/org_provisioning.py` (verbatim) |
+| `contract.py` | `load_contract` / `validate_contract` — fixture loader + code↔contract consistency check | MCP `core/ontology-permission-contract.json` + `test_permission_contract.py` |
+
+Instance-specific config (CH host/port/creds, `grant_to` service user, measurement
+tables, PREWHERE profile) stays in the consuming app's environment — this package takes
+it as parameters, never hardcodes it. `provision_org_role()` already takes `grant_to`
+per call; the convenience wrapper uses `GRANT_TO_USER` (env `MCP_CLICKHOUSE_GRANT_TO_USER`,
+default `mcp_service`) — rename/re-purpose per instance when wiring a new consumer.
+
+## Usage
+
+```python
+from pt_access.jwt import Auth0TokenVerifier
+from pt_access.claims import get_org_id, get_held_products, is_pt_admin
+from pt_access.provisioning import provision_org_on_login
+
+# 1. Verify the bearer token (FastAPI dependency, etc.)
+claims = await Auth0TokenVerifier(
+    auth0_domain="point-topic.eu.auth0.com",
+    audience="<your_client_id>",   # ID token audience = client_id
+).verify_token(bearer)
+
+# 2. Provision the org's ClickHouse role + row policy (on login / session start)
+if not is_pt_admin(claims):
+    summary = provision_org_on_login(get_org_id(claims), get_held_products(claims))
+    # summary: {"role": "org_<id>", "granted_to", "using", "tables", "warnings"}
+
+# 3. Per-query scoping on the app's READ client (never SET ROLE on a shared
+#    connection — thread-local clients are shared across users):
+#    client.query(sql, settings={"role": "org_<id>"})
+```
+
+`provision_org_on_login` is a no-op when `CLICKHOUSE_PROVISIONING_USER`/`_PASSWORD` are
+unset; without a provisioning credential orgs fail closed on the engine (role never
+granted). Requires `SUB_SITE_MONGODB_URI` (read-only sub-site Mongo user) for the fresh
+per-org read.
+
+## Behaviour contract (do not "fix" — each rule exists because of a live incident)
+
+- **Fail closed**: no held data-source products → deny (`REVOKE` role + row policy
+  `USING 0`); unknown/empty filter fields → that dataset excluded, ALL excluded →
+  deny; a held product with no stored values → bare `(DATA_SOURCE='<ds>')` (omit-empty
+  contract = full access to that product's data).
+- **Per-dataset disjunction**: `(DATA_SOURCE='upc' AND <geo>) OR (DATA_SOURCE='gbs')` —
+  never a bare `DATA_SOURCE IN (...) AND <geo>` blob.
+- **OR-grouping**: multiple predicates must be wrapped `(A OR B)` *inside* the
+  `DATA_SOURCE` guard — SQL precedence otherwise leaks other datasets' rows at the
+  postcode (found live on prod 2026-08-05).
+- **PREWHERE**: row policies on non-sorting-key columns return 0 rows under PREWHERE
+  (ClickHouse GH #85222). Provisioning creates a settings profile
+  (`optimize_move_to_prewhere = 0`) and attaches it to the **service user** — per-query
+  `SETTINGS` is blocked under `readonly=1` (error 164) and role-attached profiles don't
+  apply. Trade-off: applies to every query through that user.
+- **Convergence**: full re-provision on every login (no drift check, ~320ms), serialised
+  by a global lock (row-policy `DROP+CREATE` races → `ACCESS_ENTITY_ALREADY_EXISTS`,
+  code 493). Deny orgs are always re-provisioned too (REVOKE converges).
+- **Escaping**: every literal is single-quote-doubled (`King's Lynn`); the row policy is
+  the enforcement boundary, so a quote in an admin-entered value must never escape the
+  literal.
+
+## The contract fixture — the single evolvable artifact
+
+`src/pt_access/ontology-permission-contract.json` mirrors
+`sub-site/apps/ui/src/organisations/config/ontology-permission-contract.json`
+(sub-site UI renders exactly what this declares). Adding a **new data source** = a
+`dataSources` entry; a **new filter field** = a `fields` entry (+ `fieldProducts` /
+`compatibility` where applicable). Both are fixture changes, never composer code
+changes. The package CI drift-guard workflow fetches the sub-site copy via `gh api` and
+fails on mismatch; `tests/test_contract.py` (via `contract.validate_contract()`) checks
+the code constants against the fixture.
+
+## Consumers
+
+| App | Status | Notes |
+|---|---|---|
+| `point-topic-mcp` | to migrate | swap local modules for this package; keep FastMCP middleware + tool→product map |
+| `onto-app-new` | to integrate | issue #25; adds `ontology_app` product (role admin/viewer), JWT auth on all routes, per-query role settings |
+| `upc_query_agent` | follow-up | already reads `pt_org_id`/`products[]` in `api/auth_handler.py` — adopt `claims.py` |
+| `local-pricing-dashboard`, `european-fttp-forecasts` | don't break | read `products[].permissions.role` — the claim shape is pinned by tests |
+
+## Development
+
+```bash
+uv sync                        # or use any venv with the deps
+uv run pytest -q               # 93 tests, no network/DB needed (all mocked)
+uv run ruff check src tests
+uv run pyright                 # requires pyright install; config in pyproject
+```
+
+Distribution: private GitHub tag, pinned by consumers
+(`pip install git+https://github.com/Point-Topic/point-topic-access@v0.1.0`).

point_topic_access-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pt_access/__init__.py,sha256=w7fm3sh4-t4L-9vh7GqVuENnBnUu6eR8RzypXlDK6Q4,618
+pt_access/claims.py,sha256=ZZhA-GhiX_pZDZ5_VXOZj2qpANviRaga0LQmHN0DJDE,3616
+pt_access/composer.py,sha256=vYRLLOAO_X8UZBWHuNyzjtP63B4mSDqsG3KNdAh12rA,11222
+pt_access/contract.py,sha256=D47efpBtI7iGExQ5_mZw2a3t7J2TgYr_1NJvss_IKr8,2659
+pt_access/jwt.py,sha256=viYBdNXLobAJoVDGDoYdh3U_rkpk_2bHWex4g9Amkj4,5810
+pt_access/ontology-permission-contract.json,sha256=HD3I34xtbWidMv2n7Z97EvCwhN2p2welSd5vI1DsGlM,504
+pt_access/provisioning.py,sha256=G56JehsVSXxhoLlb3y7RkoavlfiaTqkwIGbJDlyZB8g,16085
+point_topic_access-0.1.0.dist-info/METADATA,sha256=TSBrVyXo9meGltuL7XqK8dysKkKxxIG6Jy-eeUBTvjI,7884
+point_topic_access-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+point_topic_access-0.1.0.dist-info/RECORD,,

point_topic_access-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pt_access/__init__.py

@@ -0,0 +1,15 @@
+"""pt-access: shared permission → ClickHouse access-control logic.
+
+Centralises the permission pipeline used by Point Topic's data apps (MCP
+server, ontology web app, query agent):
+
+    JWT claims ──► policy spec ──► SQL predicate ──► ClickHouse DDL
+    (what you  (normalised    (composer:      (provisioning:
+     have)      dataset +      escaping,       role, grants,
+                filter rows)   containment,    row policies,
+                               OR-grouping)    settings profile)
+
+See README.md for the architecture and HANDOFF.md for the full context.
+"""
+
+__version__ = "0.1.0"

pt_access/claims.py

@@ -0,0 +1,97 @@
+"""JWT claim helpers — the identity/entitlement surface every app shares.
+
+Ported from point-topic-mcp auth/middleware.py (the FastMCP middleware itself
+stays in the MCP; these pure functions are transport-agnostic and take claims
+as an argument — no request context).
+
+JWT shape (Auth0 post-login Action, live-verified): `pt_org_id`,
+`pt_org_name`, `products[]` as `[{name, permissions}]` — or legacy flat
+strings, handled defensively.
+
+Claim contract (FREEZE — additive-only changes):
+- `pt_org_id`, `pt_org_name` (NOT `org_id`/`org_name`: Auth0 reserved names)
+- `products[]` entries: `{"name": "<product_id>", "permissions": {<scalar fields>}}`
+  — `permissions` holds SCALAR values only (e.g. `role`); list-valued geo
+  filters are NEVER stamped into tokens (token size / proxy header limits),
+  they are read fresh from sub-site MongoDB. Client apps
+  (local-pricing-dashboard, european-fttp-forecasts) read
+  `products[].permissions.role` — do not change this shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pt_access.provisioning import ALL_DATA_SOURCES, POINT_TOPIC_ORG_ID
+
+
+def get_org_id(claims: dict | None) -> str | None:
+    """Org id from claims (`pt_org_id`)."""
+    return (claims or {}).get("pt_org_id")
+
+
+def get_held_products(claims: dict | None) -> list[str]:
+    """Product names from the JWT `products[]` claim.
+
+    Handles both the current shape (`[{name, permissions}]`) and legacy flat
+    strings (`["ukplus", "gbs"]`).
+    """
+    held: list[str] = []
+    for entry in (claims or {}).get("products") or []:
+        if isinstance(entry, dict):
+            name = entry.get("name")
+            if isinstance(name, str):
+                held.append(name)
+        elif isinstance(entry, str):
+            held.append(entry)
+    return held
+
+
+def is_pt_admin(claims: dict | None) -> bool:
+    """True when the request is from the Point Topic org (internal admin)."""
+    return get_org_id(claims) == POINT_TOPIC_ORG_ID
+
+
+def has_data_source_access(claims: dict | None) -> bool:
+    """True when the org holds any data-source product (or legacy `ontology`).
+
+    The ontology tool family is unlocked by ANY data-source product (sub-site
+    PR #110: one product per DATA_SOURCE). The retired `ontology` product name
+    is still accepted during the transition window so pre-cutover tokens keep
+    working.
+    """
+    held = set(get_held_products(claims))
+    return bool(held & set(ALL_DATA_SOURCES)) or "ontology" in held
+
+
+def get_product_permission(claims: dict | None, product: str, field: str) -> Any:
+    """A scalar permission value for one product, e.g. the app role.
+
+    ``products[].permissions`` holds scalar values only (the Action stamps
+    non-object values; list-valued geo filters never reach the token).
+    Returns None when the product or field is absent.
+    """
+    for entry in (claims or {}).get("products") or []:
+        if isinstance(entry, dict) and entry.get("name") == product:
+            permissions = entry.get("permissions") or {}
+            if isinstance(permissions, dict):
+                return permissions.get(field)
+            return None
+    return None
+
+
+def get_product_role(claims: dict | None, product: str) -> str | None:
+    """Convenience: the `role` permission of one product (e.g. admin/viewer)."""
+    role = get_product_permission(claims, product, "role")
+    return role if isinstance(role, str) else None
+
+
+__all__ = [
+    "get_org_id",
+    "get_held_products",
+    "is_pt_admin",
+    "has_data_source_access",
+    "get_product_permission",
+    "get_product_role",
+    "POINT_TOPIC_ORG_ID",
+]

pt_access/composer.py

@@ -0,0 +1,258 @@
+"""Compose per-org geography filters (sql_filter) for ClickHouse row policies.
+
+Ported from point-topic-mcp core/sql_filter_composer.py (issue #105, now
+issue #25 of Point-Topic/onto-app-new). Turns the sub-site's structured
+ontology permission config —
+``productPermissions.ontology.datasets = { <ds>: { filters: [{field, values[]}] } }``
+— into the per-dataset disjunction consumed by provisioning.
+
+The disjunction is deliberately per-dataset, each disjunct guarded by its own
+DATA_SOURCE literal::
+
+    (DATA_SOURCE='upc' AND <geo>) OR (DATA_SOURCE='upc_takeup' AND <geo>)
+    OR (DATA_SOURCE='global_tariffs')
+
+Never emit a bare ``DATA_SOURCE IN (...) AND (<geo>)`` blob — the geo
+predicate would double-wrap and silently intersect datasets.
+
+Within a dataset, multiple filter rows are **OR**-combined (union): each row
+grants an additional allowed area. This matches the "add another filter"
+grant model in the sub-site UI. Consequence: a broad row subsumes narrower
+ones (a ``country``/``home_nation`` row plus LA/postcode rows → the whole
+country matches), so the composer warns on that combination.
+
+This module only builds SQL text. It never executes anything; the row policy
+is the enforcement boundary (see infrastructure/provision_org_role.py).
+
+Verified SQL shapes (live ClickHouse, 2026-08-03):
+    Country:  COUNTRY IN ('United Kingdom')
+    LA:       LOCATION_NAME IN (SELECT ANCESTOR FROM ontology.cto_containment_assertion
+              WHERE ANCESTOR_TYPE='postcode' AND DESCENDANT_TYPE='la_name'
+              AND DESCENDANT IN (...) AND VALID_TO IS NULL)
+    Home nation: LOCATION_NAME IN (SELECT ANCESTOR FROM ontology.cto_containment_assertion
+              WHERE ANCESTOR_TYPE='postcode' AND DESCENDANT_TYPE='home_nation'
+              AND DESCENDANT IN ('England') AND VALID_TO IS NULL)
+    Postcode: LOCATION_NAME IN ('AB1 2CD', 'DD1 4HN')
+"""
+
+import re
+
+# v1 geography dimensions (registry-driven in the sub-site config). Adding a
+# dimension = add the constant, a compose branch, and a config entry.
+FIELD_COUNTRY = "country"
+FIELD_LA = "la"
+FIELD_POSTCODE = "postcode"
+FIELD_HOME_NATION = "home_nation"
+
+GEO_FIELDS = (FIELD_COUNTRY, FIELD_LA, FIELD_POSTCODE, FIELD_HOME_NATION)
+
+# ONS LA codes: one letter (E/W/S/N) + 8 digits, e.g. E09000001.
+LA_CODE_RE = re.compile(r"^[EWNS][0-9]{8}$")
+
+# The containment table that resolves postcode → LA (name or code). Fully
+# qualified, matching the live-verified policy shape.
+CONTAINMENT_TABLE = "ontology.cto_containment_assertion"
+
+# Dataset ↔ dimension compatibility, warn level. UK-geography fields (country,
+# home_nation, la, postcode) on these datasets return 0 rows or are
+# misleading: pcd_checker / edgap_ekg are European (no UK postcode
+# containment), ebm is NUTS3-scoped, gbs and global_tariffs are mostly
+# non-UK. Any dataset not listed is compatible with all geography fields.
+# Only "warn" exists today; kept as a table so stricter levels can be added
+# without code change.
+DATASET_FIELD_COMPATIBILITY: dict[str, dict[str, str]] = {
+    "pcd_checker": {
+        FIELD_COUNTRY: "warn", FIELD_HOME_NATION: "warn", FIELD_LA: "warn", FIELD_POSTCODE: "warn"
+    },
+    "edgap_ekg": {
+        FIELD_COUNTRY: "warn", FIELD_HOME_NATION: "warn", FIELD_LA: "warn", FIELD_POSTCODE: "warn"
+    },
+    "ebm": {
+        FIELD_COUNTRY: "warn", FIELD_HOME_NATION: "warn", FIELD_LA: "warn", FIELD_POSTCODE: "warn"
+    },
+    "gbs": {
+        FIELD_COUNTRY: "warn", FIELD_HOME_NATION: "warn", FIELD_LA: "warn", FIELD_POSTCODE: "warn"
+    },
+    "global_tariffs": {
+        FIELD_COUNTRY: "warn", FIELD_HOME_NATION: "warn", FIELD_LA: "warn", FIELD_POSTCODE: "warn"
+    },
+}
+
+
+def escape_sql_string(value: str) -> str:
+    """Escape a value as a ClickHouse single-quoted string literal.
+
+    Every literal ``'`` becomes ``''``. Required for correctness (King's Lynn)
+    and security: the row policy is the enforcement boundary, so a quote in an
+    admin-entered value must never break out of the literal (self-escalation).
+    """
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _clean_values(values: list[str | None] | None) -> list[str]:
+    """Strip whitespace, drop empties and duplicates, preserve first-seen order.
+
+    Non-string entries (e.g. None from a pasted list) are skipped deliberately.
+    """
+    cleaned: list[str] = []
+    seen: set[str] = set()
+    for value in values or []:
+        if not isinstance(value, str):
+            continue
+        value = value.strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        cleaned.append(value)
+    return cleaned
+
+
+def _in_list(values: list[str]) -> str:
+    """``('a', 'b')`` from a value list, each literal escaped."""
+    return ", ".join(escape_sql_string(v) for v in values)
+
+
+def compose_geo_predicate(field: str, values: list[str | None] | None) -> tuple[str, list[str]]:
+    """Build the SQL predicate for one filter row.
+
+    Args:
+        field: One of the GEO_FIELDS.
+        values: Raw admin-entered values (list/CSV pasted). Cleaned internally.
+
+    Returns:
+        (predicate, warnings). Empty predicate with a warning when the row has
+        no usable values (filter skipped).
+
+    Raises:
+        ValueError: Unknown field. Callers with config-driven input should
+            pre-check against GEO_FIELDS (compose_sql_filter does).
+    """
+    cleaned = _clean_values(values)
+    if not cleaned:
+        return "", [f"Filter field '{field}' has no usable values — skipped"]
+
+    if field == FIELD_COUNTRY:
+        return f"COUNTRY IN ({_in_list(cleaned)})", []
+
+    if field == FIELD_POSTCODE:
+        return f"LOCATION_NAME IN ({_in_list(cleaned)})", []
+
+    if field == FIELD_LA:
+        codes = [v for v in cleaned if LA_CODE_RE.match(v)]
+        names = [v for v in cleaned if not LA_CODE_RE.match(v)]
+        preds: list[str] = []
+        for dtype, subset in (("la_code", codes), ("la_name", names)):
+            if subset:
+                preds.append(
+                    f"LOCATION_NAME IN (SELECT ANCESTOR FROM {CONTAINMENT_TABLE} "
+                    f"WHERE ANCESTOR_TYPE='postcode' AND DESCENDANT_TYPE='{dtype}' "
+                    f"AND DESCENDANT IN ({_in_list(subset)}) AND VALID_TO IS NULL)"
+                )
+        if len(preds) == 1:
+            return preds[0], []
+        # Mixed codes + names in one paste: a postcode is inside an LA that is
+        # listed by code OR by name — combine with OR.
+        return "(" + " OR ".join(preds) + ")", []
+
+    if field == FIELD_HOME_NATION:
+        # UK nations (England/Wales/Scotland/NI) are a containment level, NOT
+        # the COUNTRY column — COUNTRY is 'United Kingdom' for every UK row.
+        return (
+            f"LOCATION_NAME IN (SELECT ANCESTOR FROM {CONTAINMENT_TABLE} "
+            f"WHERE ANCESTOR_TYPE='postcode' AND DESCENDANT_TYPE='home_nation' "
+            f"AND DESCENDANT IN ({_in_list(cleaned)}) AND VALID_TO IS NULL)",
+            [],
+        )
+
+    raise ValueError(f"Unknown geography field: {field}")
+
+
+def compose_sql_filter(datasets: dict[str, dict] | None) -> tuple[str, list[str]]:
+    """Compose the per-dataset disjunction for an org's row policy.
+
+    Args:
+        datasets: Sub-site config, ``{ <data_source>: {filters: [{field, values[]}] } }``.
+            A dataset with **no filter rows** yields a bare ``(DATA_SOURCE='<ds>')``
+            disjunct — checked-but-unscoped, the legitimate "whole dataset" case.
+            A dataset whose filter rows produce no usable geography predicate
+            (empty values / unknown field) is **excluded** (fail closed): a
+            slipped empty filter must not silently open the whole dataset.
+
+    Returns:
+        (sql, warnings). Empty sql (no warnings) when no datasets are
+        configured — the caller treats that as "no policy" (deny).
+    """
+    disjuncts: list[str] = []
+    warnings: list[str] = []
+
+    for ds, config in (datasets or {}).items():
+        if not isinstance(ds, str) or not ds.strip():
+            warnings.append("Ignored dataset entry with an empty name")
+            continue
+
+        filters = (config or {}).get("filters") or []
+        had_filter_rows = bool(filters)
+        preds: list[str] = []
+        for f in filters:
+            field = (f or {}).get("field")
+            if field not in GEO_FIELDS:
+                warnings.append(f"Dataset '{ds}': unknown filter field '{field}' — ignored")
+                continue
+            compat = DATASET_FIELD_COMPATIBILITY.get(ds, {}).get(field)
+            if compat == "warn":
+                warnings.append(
+                    f"Dataset '{ds}': '{field}' filter may not match this dataset's "
+                    f"rows (UK geography on '{ds}' can return 0 rows or is misleading)"
+                )
+            pred, pred_warnings = compose_geo_predicate(field, (f or {}).get("values"))
+            warnings.extend(pred_warnings)
+            if pred:
+                preds.append(pred)
+
+        if preds:
+            # A broad row (whole country / home nation) subsumes narrower LA
+            # and postcode rows when OR-combined — warn, don't drop silently.
+            filter_fields = {
+                (f or {}).get("field") for f in filters if (f or {}).get("field") in GEO_FIELDS
+            }
+            if len(preds) > 1 and {FIELD_COUNTRY, FIELD_HOME_NATION} & filter_fields:
+                warnings.append(
+                    f"Dataset '{ds}': a 'country'/'home_nation' filter OR-combined with "
+                    f"other filters matches every row of that country — the LA/postcode "
+                    f"rows are subsumed"
+                )
+            joined = " OR ".join(f"({p})" for p in preds)
+            # Multiple predicates MUST be grouped: without the wrapping parens,
+            # SQL precedence turns `(DATA_SOURCE='upc' AND (la) OR (postcode))`
+            # into `((DATA_SOURCE='upc' AND (la)) OR (postcode))` — the
+            # postcode predicate escapes the DATA_SOURCE guard and leaks rows
+            # of other datasets at that postcode (found live on prod, 2026-08-05).
+            geo = f"({joined})" if len(preds) > 1 else joined
+            disjuncts.append(f"(DATA_SOURCE={escape_sql_string(ds)} AND {geo})")
+        elif had_filter_rows:
+            # The admin engaged the filter UI for this dataset but no usable
+            # geography predicate came out of it. Excluding the dataset is the
+            # fail-closed choice — a slipped empty filter must not open the
+            # whole dataset ("no filter" is expressed by having NO filter rows).
+            warnings.append(
+                f"Dataset '{ds}': filter rows present but none produced a usable "
+                f"geography predicate — dataset excluded (fail closed)"
+            )
+        else:
+            # Checked with no filter rows → the whole dataset, no geography.
+            disjuncts.append(f"(DATA_SOURCE={escape_sql_string(ds)})")
+
+    return " OR ".join(disjuncts), warnings
+
+
+__all__ = [
+    "compose_sql_filter",
+    "compose_geo_predicate",
+    "escape_sql_string",
+    "GEO_FIELDS",
+    "FIELD_COUNTRY",
+    "FIELD_LA",
+    "FIELD_POSTCODE",
+    "FIELD_HOME_NATION",
+    "DATASET_FIELD_COMPATIBILITY",
+]

pt_access/contract.py

@@ -0,0 +1,70 @@
+"""Contract fixture loading + validation — the single evolvable artifact.
+
+The fixture (`src/pt_access/ontology-permission-contract.json`) mirrors the
+sub-site's copy (`apps/ui/src/organisations/config/
+ontology-permission-contract.json`) — the sub-site UI renders exactly the
+fields/products declared here, and the package's composer/provisioning
+interpret them. If the two drift, the sub-site UI can save permission values
+the composer doesn't understand — and an org silently loses access on its
+next login (the composer fail-closes on unknown fields).
+
+The package CI runs a drift-guard workflow that fetches the sub-site copy via
+`gh api` and fails on mismatch. When changing either side, update BOTH
+fixtures and both test suites.
+
+Contract evolution rule: a new data source = a `dataSources` entry; a new
+filter field = a `fields` entry (+ `fieldProducts` + `compatibility` entries
+if applicable) — both are DATA changes, never code changes (the declarative
+refactor of the composer consumes this fixture directly).
+"""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+from pt_access import composer, provisioning
+
+
+def load_contract() -> dict:
+    """Load the packaged contract fixture."""
+    fixture = resources.files("pt_access").joinpath("ontology-permission-contract.json")
+    return json.loads(fixture.read_text(encoding="utf-8"))
+
+
+def validate_contract() -> list[str]:
+    """Check the code's constants against the fixture.
+
+    Returns a list of mismatch descriptions; empty list = consistent. Used by
+    the drift-guard tests and CI.
+    """
+    mismatches: list[str] = []
+    contract = load_contract()
+
+    code_ds = set(provisioning.ALL_DATA_SOURCES)
+    contract_ds = set(contract.get("dataSources", []))
+    if code_ds != contract_ds:
+        mismatches.append(
+            f"dataSources mismatch: code={sorted(code_ds)} contract={sorted(contract_ds)}"
+        )
+
+    code_fields = set(composer.GEO_FIELDS)
+    contract_fields = set(contract.get("fields", []))
+    if code_fields != contract_fields:
+        mismatches.append(
+            f"fields mismatch: code={sorted(code_fields)} contract={sorted(contract_fields)}"
+        )
+
+    for ds, fields in (contract.get("fieldProducts") or {}).items():
+        if ds not in contract_ds:
+            mismatches.append(f"fieldProducts references unknown data source '{ds}'")
+        unknown = set(fields) - contract_fields
+        if unknown:
+            mismatches.append(
+                f"fieldProducts['{ds}'] references unknown fields {sorted(unknown)}"
+            )
+
+    return mismatches
+
+
+__all__ = ["load_contract", "validate_contract"]

pt_access/jwt.py

@@ -0,0 +1,153 @@
+"""Auth0 JWT verification via JWKS — shared by every Point Topic app backend.
+
+Ported from point-topic-mcp auth/auth0_helpers.py (the FastMCP
+TokenVerifier adapter stays in the MCP; this is the pure verifier).
+
+Usage (FastAPI dependency or any async path)::
+
+    verifier = Auth0TokenVerifier(auth0_domain="point-topic.eu.auth0.com",
+                                  audience="<client_id>")
+    claims = await verifier.verify_token(bearer_token)   # None when invalid
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+import httpx
+from jose import JWTError, jwk, jwt
+
+logger = logging.getLogger(__name__)
+
+
+class Auth0TokenVerifier:
+    """JWT token verifier using the Auth0 JWKS endpoint.
+
+    Validates tokens issued by the shared Auth0 tenant: signature (RS256),
+    issuer, expiry and audience. The JWKS is cached with a TTL so key
+    rotation doesn't lock users out until restart.
+    """
+
+    def __init__(
+        self,
+        auth0_domain: str,
+        audience: str | list[str],
+        jwks_url: str | None = None,
+    ):
+        """Args:
+            auth0_domain: Auth0 tenant domain (e.g. 'point-topic.eu.auth0.com').
+            audience: Accepted audience(s). May be a single string, a
+                comma-separated string, or a list. Sub-site tokens carry
+                'http://ss-api'; tokens minted for the MCP resource (RFC 9728)
+                carry the resource URL (e.g. 'https://mcp.point-topic.com/mcp');
+                ID tokens from express-openid-connect carry the app's
+                client_id.
+            jwks_url: Optional JWKS URL. Defaults to
+                https://{domain}/.well-known/jwks.json
+        """
+        self.auth0_domain = auth0_domain
+        if isinstance(audience, str):
+            self.audiences = [a.strip() for a in audience.split(",") if a.strip()]
+        else:
+            self.audiences = list(audience or [])
+        self.jwks_url = jwks_url or f"https://{auth0_domain}/.well-known/jwks.json"
+        self._jwks: dict | None = None
+        self._jwks_fetched_at: float | None = None
+        # Refresh the cached JWKS after this long (seconds) so Auth0 key
+        # rotation doesn't lock users out until the process restarts.
+        self._jwks_ttl = 3600
+
+    async def _get_jwks(self) -> dict | None:
+        """Fetch JWKS from Auth0, cached with a TTL for key rotation."""
+        now = time.time()
+        if self._jwks is None or self._jwks_fetched_at is None or now - self._jwks_fetched_at > self._jwks_ttl:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(self.jwks_url)
+                response.raise_for_status()
+                self._jwks = response.json()
+                self._jwks_fetched_at = now
+        return self._jwks
+
+    async def verify_token(self, token: str) -> dict | None:
+        """Verify and decode a JWT token.
+
+        Returns:
+            Decoded token claims dict if valid, None otherwise.
+        """
+        try:
+            jwks = await self._get_jwks()
+            if jwks is None:
+                logger.warning("Failed to fetch JWKS")
+                return None
+            signing_key = self._get_signing_key(token, jwks)
+
+            if not signing_key:
+                logger.warning("No signing key found for token")
+                return None
+
+            # Construct a proper key object from the JWK dict
+            try:
+                key = jwk.construct(signing_key)
+            except Exception as e:
+                logger.warning(f"Failed to construct signing key: {e}")
+                return None
+
+            # Decode and verify the token. Verify signature/issuer/exp via
+            # python-jose but defer audience to the manual check below so any
+            # of the accepted audiences passes (python-jose takes a single
+            # audience string only).
+            payload = jwt.decode(
+                token,
+                key,
+                issuer=f"https://{self.auth0_domain}/",
+                options={"verify_aud": False},
+            )
+
+            # Audience must be one of the accepted values (aud may be a
+            # single string or a list in the token).
+            aud_claims = payload.get("aud")
+            if isinstance(aud_claims, str):
+                aud_claims = [aud_claims]
+            if not aud_claims or not any(a in self.audiences for a in aud_claims):
+                logger.warning(
+                    f"Token audience {payload.get('aud')} not accepted "
+                    f"(expected one of {self.audiences})"
+                )
+                return None
+
+            return payload
+
+        except jwt.ExpiredSignatureError:  # type: ignore
+            logger.warning("Token has expired")
+        except jwt.JWTClaimsError as e:  # type: ignore
+            logger.warning(f"Token claims error: {e}")
+        except JWTError as e:
+            logger.warning(f"JWT validation error: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error verifying token: {e}")
+
+        return None
+
+    def _get_signing_key(self, token: str, jwks: dict) -> dict | None:
+        """Extract the signing key from JWKS matching the token's kid."""
+        try:
+            headers = jwt.get_unverified_header(token)
+            kid = headers.get("kid")
+            if not kid:
+                return None
+
+            for key in jwks.get("keys", []):
+                if key.get("kid") == kid:
+                    return key
+        except JWTError as e:
+            logger.warning(f"Failed to extract token header: {e}")
+
+        return None
+
+    async def get_token_claims(self, token: str) -> dict | None:
+        """Get claims from a token (wrapper around verify_token)."""
+        return await self.verify_token(token)
+
+
+__all__ = ["Auth0TokenVerifier"]

pt_access/ontology-permission-contract.json

@@ -0,0 +1,23 @@
+{
+  "dataSources": [
+    "upc",
+    "upc_takeup",
+    "upc_forecasts",
+    "global_tariffs",
+    "gbs",
+    "bddi",
+    "arpu",
+    "ebm",
+    "pcd_checker",
+    "roadworks",
+    "ofcom_tar",
+    "edgap_ekg"
+  ],
+  "fields": ["country", "home_nation", "la", "postcode"],
+  "fieldProducts": {
+    "upc": ["home_nation", "la", "postcode"],
+    "upc_takeup": ["home_nation", "la", "postcode"],
+    "upc_forecasts": ["home_nation", "la", "postcode"],
+    "roadworks": ["home_nation", "la", "postcode"]
+  }
+}

pt_access/provisioning.py

@@ -0,0 +1,381 @@
+"""Per-org ClickHouse provisioning on login.
+
+Ported from point-topic-mcp core/org_provisioning.py (issue #104/#105, now
+issue #25 of Point-Topic/onto-app-new). Every successful login from an org
+unconditionally re-provisions that org's ClickHouse role + RESTRICTIVE row
+policy from the sub-site's *fresh* config — no drift check, no stored state
+(full re-provision measures ~320ms on prod). Converges to whatever the
+sub-site currently says: a UI change is applied on the org's next login, a
+revoked org is narrowed on its next login, and manual misconfiguration
+self-heals.
+
+Mechanism (verified on prod 2026-08-03):
+    CREATE ROLE IF NOT EXISTS org_<id>
+    GRANT SELECT ON ontology.* TO org_<id>
+    GRANT org_<id> TO mcp_service            (org with config)
+    REVOKE org_<id> FROM mcp_service         (org with no config → deny)
+    DROP ROW POLICY IF EXISTS + CREATE ROW POLICY ... AS RESTRICTIVE TO org_<id>
+      on every table in MEASUREMENT_TABLES
+    CREATE SETTINGS PROFILE IF NOT EXISTS mcp_scoped_org_prewhere
+      SETTINGS optimize_move_to_prewhere = 0
+    ALTER USER mcp_service ADD PROFILES 'mcp_scoped_org_prewhere'
+      (attached to the service user, not org roles — see PREWHERE note)
+
+The row policy condition is the composer's per-dataset disjunction (see
+core/sql_filter_composer.py). An org with no datasets config gets a deny-all
+policy (USING 0) and its role is revoked from the service user — fail closed.
+
+PREWHERE fix (verified live 2026-08-05, ClickHouse GH #85222): a row policy
+whose condition references non-sorting-key columns (LOCATION_NAME via the
+containment subquery, COUNTRY) evaluates to 0 rows because ClickHouse applies
+policies inside PREWHERE, where only sorting-key columns are read — the
+missing columns default to empty and every row is filtered. Disabling
+PREWHERE (optimize_move_to_prewhere=0) applies the policy where all columns
+are available.
+
+Where the setting lives (live-tested): per-query SETTINGS is blocked for
+mcp_service (readonly=1 → error 164) and a profile attached to an org role is
+NOT applied when the role is activated under readonly. The one working lever
+is a settings profile attached to the SERVICE USER: it applies at connection
+time, before the readonly check. Trade-off: it applies to every query through
+mcp_service, so the Point Topic org's full-scan queries also run with PREWHERE
+disabled (correctness for all orgs wins over that optimization; the sorting
+key still prunes via the primary index).
+
+Credentials: ONE dedicated provisioning credential, never shared with
+`mcp_service` (which stays readonly=1 / allow_ddl=0):
+    CLICKHOUSE_PROVISIONING_USER / CLICKHOUSE_PROVISIONING_PASSWORD
+Host/port/database default from the CLICKHOUSE_* vars (same endpoint,
+different user). The provisioning user needs ACCESS MANAGEMENT to create
+roles/policies/grants; it can bypass row policies by design — it is stored in
+secrets and never exposed.
+
+The org's geography values are read from the sub-site MongoDB (fresh per
+login): flat per-product permissions —
+``organisations.productPermissions.<data_source> = {field: string[]}`` — one
+entry per data-source product the org holds (sub-site PR #110 contract, see
+ontology-permission-contract.json). The set of data-source products the org
+holds comes from the JWT products[] (the same list the tool gate uses);
+absent permission values for a held product mean full access to that
+product's data (omit-empty contract). Requires SUB_SITE_MONGODB_URI (read-only
+user).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Any
+from urllib.parse import urlparse
+
+from bson import ObjectId
+from pymongo import MongoClient
+
+from pt_access.composer import (
+    compose_sql_filter,
+    escape_sql_string,
+)
+
+logger = logging.getLogger(__name__)
+
+# Serialize the DDL across concurrent logins: two initializes for the same
+# org race on DROP ROW POLICY IF EXISTS + CREATE ROW POLICY (no CREATE OR
+# REPLACE exists), and the loser fails with ACCESS_ENTITY_ALREADY_EXISTS
+# (code 493, seen live on prod 2026-08-06). A global lock is plenty —
+# provisioning is ~320ms and logins are rare; concurrent logins just queue.
+_PROVISION_LOCK = threading.Lock()
+
+
+# Measurement-bearing tables needing row policies (extend via get_onto_schema
+# if more appear). Reference tables stay open via the role's ontology.* grant.
+MEASUREMENT_TABLES = [
+    "ontology.cto_measurement_record",
+    "ontology.cto_measurement_record_staging",
+]
+
+# The 12 live DATA_SOURCEs (verified on prod 2026-08-03). The Point Topic
+# org's full-access role covers exactly these — add new sources here so the
+# admin role keeps seeing them.
+ALL_DATA_SOURCES = [
+    "upc",
+    "upc_takeup",
+    "upc_forecasts",
+    "global_tariffs",
+    "gbs",
+    "bddi",
+    "arpu",
+    "ebm",
+    "pcd_checker",
+    "roadworks",
+    "ofcom_tar",
+    "edgap_ekg",
+]
+
+# Point Topic org — internal admin, full access (env-overridable; mirrors
+# POINT_TOPIC_ORG_ID in auth/middleware.py).
+POINT_TOPIC_ORG_ID = os.getenv("POINT_TOPIC_ORG_ID", "65dc868c4f33e6b7d256fab4")
+
+# The least-privilege service user that activates org roles per request.
+GRANT_TO_USER = os.getenv("MCP_CLICKHOUSE_GRANT_TO_USER", "mcp_service")
+
+# Deny-all row policy condition: matches no rows (documented ClickHouse
+# pattern). Used when an org has no datasets config — fail closed until an
+# admin configures geography in the sub-site.
+DENY_USING = "0"
+
+# Settings profile that disables PREWHERE for scoped orgs (see the module
+# docstring: row policies on non-sorting-key columns return 0 rows under
+# PREWHERE, GH #85222). Attached to the SERVICE USER (GRANT_TO_USER) — a
+# role-attached profile is not applied under readonly=1, but a user-attached
+# one applies at connection time. Applies to all queries through the service
+# user (including the Point Topic org).
+SCOPED_ORG_PREWHERE_PROFILE = "mcp_scoped_org_prewhere"
+
+# Short timeouts on the sub-site read so a DB outage never stalls a login.
+# Values are Any so Pyright resolves the **kwargs against MongoClient's
+# overloads (typed ints mis-resolve against the TypeRegistry parameter).
+_SUB_SITE_CLIENT_OPTS: dict[str, Any] = {
+    "connectTimeoutMS": 3000,
+    "serverSelectionTimeoutMS": 5000,
+}
+
+
+def provisioning_configured() -> bool:
+    """Whether the dedicated provisioning credential is present in env."""
+    return bool(os.getenv("CLICKHOUSE_PROVISIONING_USER") and os.getenv("CLICKHOUSE_PROVISIONING_PASSWORD"))
+
+
+def provisioning_client():
+    """ClickHouse client bound to the dedicated provisioning credential.
+
+    Returns None when the credential is not configured — provisioning is
+    disabled and orgs fail closed on the engine (their roles are never
+    granted to the service user).
+    """
+    if not provisioning_configured():
+        return None
+    import clickhouse_connect
+
+    port = int(os.environ.get("CLICKHOUSE_PORT", "443"))
+    return clickhouse_connect.get_client(
+        host=os.environ["CLICKHOUSE_HOST"],
+        port=port,
+        username=os.environ["CLICKHOUSE_PROVISIONING_USER"],
+        password=os.environ["CLICKHOUSE_PROVISIONING_PASSWORD"],
+        database=os.environ.get("CLICKHOUSE_DATABASE", "ontology"),
+        secure=port == 443,
+    )
+
+
+def fetch_org_datasets(org_id: str) -> dict[str, dict[str, list[str]]]:
+    """Read the org's flat per-product permission values from the sub-site.
+
+    Returns ``{ <data_source>: {field: [values]} }`` for every data-source
+    product present in ``productPermissions`` (omit-empty contract: a held
+    product with no stored values is absent — the caller treats absence as
+    full access to that product's data). A missing org document is treated the
+    same as "no stored values": the JWT products[] is the access gate and is a
+    ≤24h snapshot, so a deleted org's tokens keep their last-stamped access
+    until expiry.
+
+    Raises RuntimeError when SUB_SITE_MONGODB_URI is not configured.
+    """
+    uri = os.getenv("SUB_SITE_MONGODB_URI", "")
+    if not uri:
+        raise RuntimeError("SUB_SITE_MONGODB_URI is not set")
+    client = MongoClient(uri, **_SUB_SITE_CLIENT_OPTS)
+    try:
+        db_name = urlparse(uri).path.lstrip("/") or "sub-site"
+        org = client[db_name].organisations.find_one(
+            {"_id": ObjectId(org_id)}, {"productPermissions": 1}
+        )
+    finally:
+        client.close()
+    if not org:
+        logger.warning("Org %s not found in sub-site MongoDB", org_id)
+        return {}
+    # Annotated so Pyright resolves the value shape; productPermissions is
+    # free-form in Mongo (e.g. query_agent holds a number), and only
+    # data-source entries are selected below. Subscript (not .get) for the
+    # value so the guard above guarantees presence; a malformed truthy value
+    # still flows through and fails closed downstream in _filters_from_flat.
+    perms: dict[str, Any] = org.get("productPermissions") or {}
+    return {ds: perms[ds] for ds in ALL_DATA_SOURCES if perms.get(ds)}
+
+
+def _filters_from_flat(flat: dict[str, list[str]] | None) -> list[dict]:
+    """Flat ``{field: [values]}`` → composer filter rows (omit-empty).
+
+    Only fields with at least one value become rows; anything else is absent
+    and means "no predicate" for that field (the omit-empty contract).
+
+    Unknown fields are deliberately NOT dropped here: they flow through to
+    the composer, which warns and excludes the dataset (fail closed).
+    Dropping them here would silently open the whole dataset (found live
+    2026-08-06 — a field the MCP doesn't know yet must never mean full
+    access).
+    """
+    return [
+        {"field": field, "values": values}
+        for field, values in (flat or {}).items()
+        if values
+    ]
+
+
+def resolve_org_config(org_id: str, held_products: list[str] | None = None) -> tuple[list[str], str, list[str]]:
+    """Resolve (data_sources, sql_filter, warnings) for an org's row policy.
+
+    Point Topic org → full access (all data sources, no geography filter).
+    Other orgs → the data-source products the org holds (JWT products[]),
+    each composed from its sub-site permission values. A held product with no
+    stored values becomes a bare ``(DATA_SOURCE='<ds>')`` disjunct — full
+    access to that product, per the omit-empty contract. No held data-source
+    products → deny (empty data_sources → REVOKE + USING 0).
+    """
+    if org_id == POINT_TOPIC_ORG_ID:
+        return ALL_DATA_SOURCES, "", []
+    held = set(held_products or [])
+    data_sources = [ds for ds in ALL_DATA_SOURCES if ds in held]
+    if not data_sources:
+        return [], "", []
+    flat = fetch_org_datasets(org_id)
+    composer_input = {
+        ds: {"filters": _filters_from_flat(flat.get(ds))} if flat.get(ds) else {}
+        for ds in data_sources
+    }
+    sql, warnings = compose_sql_filter(composer_input)
+    if not sql and warnings:
+        # The composer excluded EVERY held dataset (unknown/invalid filter
+        # fields). Deny — an empty composed filter must never fall back to
+        # the full data-source list (provisioning's "no geography filter"
+        # signal). Fail closed, loudly: the caller logs each warning.
+        logger.warning(
+            "Org %s: all held data-source products excluded by filter config — denying",
+            org_id,
+        )
+        return [], "", warnings
+    return data_sources, sql, warnings
+
+
+def _sources_in_list(data_sources: list[str]) -> str:
+    return "DATA_SOURCE IN (" + ", ".join(escape_sql_string(s) for s in data_sources) + ")"
+
+
+def provision_org_role(client, org_id: str, data_sources: list[str], sql_filter: str, grant_to: str) -> dict:
+    """Idempotent DDL: org role + grants + RESTRICTIVE policy on both tables.
+
+    Args:
+        client: ClickHouse client with the provisioning credential (injected
+            for testability).
+        org_id: Sub-site organisation id (Mongo ObjectId hex).
+        data_sources: DATA_SOURCE allowlist; empty means deny.
+        sql_filter: Composed per-dataset disjunction ("" = no geography
+            scoping, used for the full-access role).
+        grant_to: Service user the org role is granted to (revoked on deny).
+
+    Returns:
+        Summary dict (role, granted_to, using, tables).
+    """
+    role = f"org_{org_id}"
+    client.command(f"CREATE ROLE IF NOT EXISTS {role}")
+    client.command(f"GRANT SELECT ON ontology.* TO {role}")
+
+    # Global, idempotent, self-healing (like CREATE ROLE IF NOT EXISTS).
+    client.command(
+        f"CREATE SETTINGS PROFILE IF NOT EXISTS {SCOPED_ORG_PREWHERE_PROFILE} "
+        "SETTINGS optimize_move_to_prewhere = 0"
+    )
+    # Attach the profile to the SERVICE USER, not the org role: mcp_service
+    # is readonly=1, which blocks per-query SETTINGS (error 164) and does not
+    # apply role-attached profiles when the role is activated. A user-attached
+    # profile applies at connection time. ALTER USER ... ADD PROFILES is
+    # idempotent, so this converges on every login.
+    client.command(
+        f"ALTER USER {grant_to} ADD PROFILES '{SCOPED_ORG_PREWHERE_PROFILE}'"
+    )
+
+    if data_sources:
+        using = sql_filter if sql_filter else _sources_in_list(data_sources)
+        # REVOKE is safe unconditionally (ClickHouse ignores missing grants),
+        # so deny -> revoke converges even if a previous login granted.
+        client.command(f"GRANT {role} TO {grant_to}")
+        granted_to = grant_to
+    else:
+        using = DENY_USING
+        client.command(f"REVOKE {role} FROM {grant_to}")
+        granted_to = None
+
+    for table in MEASUREMENT_TABLES:
+        # No CREATE OR REPLACE for row policies; drop + create is idempotent.
+        client.command(f"DROP ROW POLICY IF EXISTS {role}_policy ON {table}")
+        client.command(
+            f"CREATE ROW POLICY {role}_policy ON {table} "
+            f"FOR SELECT USING {using} AS RESTRICTIVE TO {role}"
+        )
+
+    return {
+        "role": role,
+        "granted_to": granted_to,
+        "using": using,
+        "tables": list(MEASUREMENT_TABLES),
+        "prewhere_profile": SCOPED_ORG_PREWHERE_PROFILE,
+    }
+
+
+def provision_org_on_login(org_id: str, held_products: list[str] | None = None) -> dict:
+    """Fetch fresh config, compose, and re-provision an org. Returns summary.
+
+    held_products: the org's JWT products[] (used to decide which
+    data-source products the org holds).
+    """
+    data_sources, sql_filter, warnings = resolve_org_config(org_id, held_products)
+    client = provisioning_client()
+    if client is None:
+        raise RuntimeError(
+            "Provisioning disabled: CLICKHOUSE_PROVISIONING_USER/PASSWORD not set"
+        )
+    try:
+        with _PROVISION_LOCK:
+            summary = provision_org_role(client, org_id, data_sources, sql_filter, GRANT_TO_USER)
+    finally:
+        client.close()
+    summary["warnings"] = warnings
+    # Loud fail-closed: unknown/invalid filter fields are a dev-time config
+    # error (MCP + sub-site shipped out of lockstep). Log every warning with
+    # the org id and full text, and an ERROR when the org is denied because
+    # of them — never swallow this into a quiet "0 rows".
+    for w in warnings:
+        logger.warning("Org %s filter warning: %s", org_id, w)
+    if not data_sources and warnings:
+        logger.error(
+            "Org %s DENIED on login: all held data-source products excluded "
+            "by filter config (unknown/invalid fields) — %s",
+            org_id,
+            warnings,
+        )
+    logger.info(
+        "Provisioned %s: %d data source(s), geo=%s, granted_to=%s, warnings=%d",
+        summary["role"],
+        len(data_sources),
+        "yes" if sql_filter else "no",
+        summary["granted_to"],
+        len(warnings),
+    )
+    return summary
+
+
+__all__ = [
+    "MEASUREMENT_TABLES",
+    "ALL_DATA_SOURCES",
+    "POINT_TOPIC_ORG_ID",
+    "GRANT_TO_USER",
+    "DENY_USING",
+    "SCOPED_ORG_PREWHERE_PROFILE",
+    "provisioning_configured",
+    "provisioning_client",
+    "fetch_org_datasets",
+    "resolve_org_config",
+    "provision_org_role",
+    "provision_org_on_login",
+]