point-topic-access 0.1.0__tar.gz

point_topic_access-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.pyright/

point_topic_access-0.1.0/HANDOFF.md

@@ -0,0 +1,140 @@
+# HANDOFF — full context for the agent continuing this repo
+
+**Read this before touching anything.** This scaffold was built inside
+`point-topic-mcp/pt-access` (2026-08-07) and is intended to be moved to
+`~/Projects/point-topic-access` and pushed as a new private repo
+(`Point-Topic/point-topic-access`). It is the shared permission logic for Point
+Topic's data apps. All 93 tests pass; no git history exists yet.
+
+## Mission
+
+Give every Point Topic data app the same identity + data-permission system the MCP
+server runs in production:
+
+1. **Identity**: sub-site Auth0 tenant (`point-topic.eu.auth0.com`) — same users/orgs
+   everywhere, no per-app logins.
+2. **Data access**: per-org `productPermissions.<data_source> = {field: string[]}` from
+   the sub-site (products + geo filters), enforced as ClickHouse RESTRICTIVE row
+   policies, provisioned fresh on every login.
+3. **One codebase for the logic** (this package) so MCP / ontology app / query agent
+   cannot drift.
+
+Tracked by **onto-app-new#25** (the plan: access model, repo-by-repo work, rollout).
+The ontology app's own ticket #18 (permissions built into the Snowflake ontology) is
+**superseded — not being built** (commented on 2026-08-07).
+
+## What was verified against live systems (2026-08-07) — trust, don't re-derive
+
+- **Geo filters stay out of the JWT** — the Auth0 Action
+  (`sub-site/terraform/modules/auth0/actions.tf`) stamps only scalar permission values;
+  its own comment documents why: lists bloat tokens to hundreds of KB, hitting proxy
+  header limits. Scope is read fresh from sub-site Mongo (this package does that).
+- **Claim shape** (freeze, additive-only): `pt_org_id`, `pt_org_name`, `products[]`
+  as `[{name, permissions:{scalar}}]`. `local-pricing-dashboard` and
+  `european-fttp-forecasts` SPAs read `products[].permissions.role` — a shape change
+  broke the local-pricing dashboard once already (2026-08-05, reverted).
+- **Action stamping is generic**: new products/roles are stamped automatically; no
+  Action change needed for the `ontology_app` product.
+- **Per-query role activation** (not SET ROLE on a shared connection): the ontology
+  app's backend uses thread-local ClickHouse clients shared across users;
+  scoping must be `client.query(sql, settings={"role": "org_<id>"})` — the pattern in
+  MCP `tools/database_tools.py::_org_role_settings`.
+- **PREWHERE fix**: profile attached to the **service user**
+  (`ALTER USER <u> ADD PROFILES 'mcp_scoped_org_prewhere'`), `optimize_move_to_prewhere=0`.
+  Live-proven failures: per-query SETTINGS under readonly → error 164;
+  `GRANT SETTINGS PROFILE ... TO <role>` is a syntax error on CH 26.3;
+  role-attached profiles don't apply under readonly.
+- **MCP ClickHouse** (`db.point-topic.com:443`) and the **ontology app's ClickHouse**
+  (docker container on 109.169.53.90, localhost:8123, user `default`) are DIFFERENT
+  instances — the app needs its own provisioning with its own service user (planned:
+  `onto_app`, readonly, DEFAULT ROLE NONE; `default` kept only for the business-data
+  refresh writes).
+- **Product schema pattern** for the new `ontology_app` product (sub-site):
+  `permissionField: 'role'`, `permissionFieldType: 'select'`,
+  `permissionFieldOptions: ['admin', 'viewer']` — same as `local_pricing`.
+- **Sub-site contract copy**: `sub-site/apps/ui/src/organisations/config/
+  ontology-permission-contract.json` (filterFields.ts is the UI registry).
+- The ontology app's edit endpoints (`POST/PUT/DELETE /api/{add,edit,delete}-entry`)
+  have **NO server-side auth today** — closing that gap is part of the integration.
+
+## Decisions locked in
+
+- **Mongo-first policy source**: `fetch_org_datasets` reads sub-site Mongo directly
+  (proven path). A future sub-site API endpoint (`/permission-policy`) can replace the
+  Mongo read behind the same spec boundary — the composer/provisioning never change.
+- **No fallback patterns** (house rule): adapters are explicit choices, never
+  try-A-else-B.
+- **Contract-driven evolution**: new data source / filter field = fixture change +
+  tests, not composer code (the declarative refactor below).
+- **Viewer/admin** for the ontology app come from `ontology_app` product role
+  (`products[].permissions.role`), NOT from a new claim.
+- **SPARQL scoping deferred**: ontop queries Snowflake, not ClickHouse — row policies
+  can't reach it; SPARQL stays PT-org-only in v1.
+
+## Next steps (in order)
+
+1. **Declarative composer refactor**: make `composer.py` interpret the fixture
+   (`fields` as data: `kind: in_literal | containment`, column, descendantTypes;
+   `compatibility` map in the fixture) instead of hardcoded branches. Golden tests
+   already pin every SQL shape — refactor with them green. (The MCP handoff's
+   proposed `GEO_DIMENSIONS` refactor — now is the time.)
+2. **`spec.py`**: the normalised policy spec (claims/Mongo → `{ds: {filters:
+   [{field, values}]}}`) as the single normalisation point — becomes the seam for the
+   sub-site API adapter.
+3. **CI workflows**: pytest + ruff + pyright; **drift guard** (fetch sub-site contract
+   copy via `gh api`, fail on mismatch); shape-pin test for the claim contract is
+   already covered in `tests/test_claims.py`.
+4. **`point-topic-mcp` swap**: delete local `core/sql_filter_composer.py`,
+   `core/org_provisioning.py`, fixture; depend on this package; keep
+   `auth/product_mapping.py`, `auth/middleware.py`, `_org_role_settings`. Verify
+   nothing else uses `SUB_SITE_MONGODB_URI` before dropping it. 242 MCP tests + E2E
+   (`infrastructure/verify_http_mcp.py`) must stay green.
+5. **`onto-app-new` integration** (issue #25): Express `express-openid-connect` v3
+   (verified current: `issuerBaseURL`, `baseURL`, `clientID`, `clientSecret`, `secret`,
+   `authRequired: false`, `auth0Logout: true`); FastAPI JWT dependency on all `/api/*`
+   (except `/health`, `/api/external/*`); `/api/me`; role gates (admin = modify/SPARQL/
+   database tools/refresh; viewer = read-only); per-query `settings={"role": ...}` in
+   `database.py`; drop `permission_service.py` Snowflake chain + `STG_USER` login +
+   `data_restrictions` client param. Verify `cto_measurement_record_staging` exists in
+   the app's CH before setting measurement tables.
+6. **Sub-site**: seed `ontology_app` product; assign PT org (admin) + client orgs;
+   no Action change. **Auth0**: new Regular Web App client (terraform in
+   `sub-site/terraform/modules/auth0/`), callbacks for
+   `ontology.point-topic.com` (+dev), secret → `ptserver-secret` AWS secret.
+7. **`upc_query_agent`**: adopt `claims.py` (it already reads the claims in
+   `api/auth_handler.py`).
+
+## Environment / secrets (never inline, never commit)
+
+- Sub-site Mongo: `~/.SUB_SITE_MONGODB_URI_PROD` / `_DEV` (read via
+  `$(cat ...)`, chmod 600, never printed).
+- Auth0 M2M: `~/.agents/.env.auth0` (`AUTH0_PROD_DOMAIN`, `AUTH0_PROD_CLIENT_ID`,
+  `AUTH0_PROD_CLIENT_SECRET`); Management API for tenant ops; terraform is the source
+  of truth for tenant config in the sub-site repo.
+- ClickHouse: MCP = `~/.clickhouse.env` on the dev Mac (host `db.point-topic.com:443`);
+  ontology app CH = docker on RapidSwitch box (`root@109.169.53.90`, key
+  `~/.ssh/rapidswitch_server`), localhost:8123.
+- Load the `credential-boundary` / `point-topic-auth0` / `sub-site-mongodb` skills for
+  any operation touching these.
+
+## House rules (user's, non-negotiable)
+
+- **Never commit/push without explicit approval.** Present the diff, wait for
+  "commit/push". The user reviews in the editor.
+- Terminal tool: pass `cd` as a parameter, never `cd X && ...` in the command.
+- `gh` account must be `peterdonaghey` (never `pt-agent`).
+- No fallback/try-A-else-B patterns in code; deliberate checks only.
+- Secrets never in commands/chat; rotate immediately if leaked.
+- The sub-site repo is read-only for agents (user explicit) — sub-site changes are
+  authored by the user or explicitly authorised.
+- This scaffold lives at `pt-access/` inside the MCP repo working tree until the user
+  moves it to `~/Projects/point-topic-access`; do not commit it as part of the MCP.
+
+## Status when handed over
+
+- `src/pt_access/`: claims, jwt, composer, provisioning, contract, fixture — ported
+  verbatim from the MCP (imports adapted), plus new claims/jwt/contract modules.
+- `tests/`: 93 tests pass (composer 39, provisioning 34, jwt 11, claims 16, contract 3)
+  via `pytest -q` (uses `pythonpath = ["src"]`; no install needed).
+- NOT done yet: declarative composer refactor, spec.py, CI workflows, any consumer
+  migration. The MCP still contains its own copies (do not delete until the swap).

point_topic_access-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "point-topic-access"
+version = "0.1.0"
+description = "Shared permission -> ClickHouse access-control logic for Point Topic apps (claims, JWT verification, geo filter composer, per-org provisioning)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+dependencies = [
+    "clickhouse-connect>=0.8.0",
+    "httpx>=0.28.0",
+    "python-jose>=3.3.0",
+    "pymongo>=4.10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.9.0",
+    "pyright>=1.1.0",
+    "cryptography>=44.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pt_access"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["src"]

point_topic_access-0.1.0/src/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"

point_topic_access-0.1.0/src/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",
+]