diff --git "a/api/deps.py" "b/api/deps.py" --- "a/api/deps.py" +++ "b/api/deps.py" @@ -1,989 +1,989 @@ -"""deps.py — the request-scoped session + tenant resolution every v1 route depends on. - -ONE place answers "who is asking, for which tenant, and what may they see?", because a -permission check that exists in four routes has four chances to be forgotten. The routes take -`session: Session = Depends(require_session)` and receive an object that has ALREADY failed -closed if anything was wrong. - -FAIL-CLOSED, spelled out (X2): no cookie → **401**. Cookie present but unverifiable, expired, -epoch-revoked, or naming an unknown tenant → **401**. Authenticated but not granted the surface → -**403**. Never an empty 200: an empty list is a legitimate answer meaning "no rows", and using it -to mean "you are not allowed" is how a permission bug becomes invisible. -""" -import copy -import os -import sys -import time -from collections import OrderedDict -from dataclasses import dataclass -from pathlib import Path - -from fastapi import Depends, HTTPException, Request, Response - -import aios_session - -_RI = Path(os.environ.get("RI_DIR") or Path(__file__).resolve().parents[2] / "platform") -if str(_RI) not in sys.path: - sys.path.insert(0, str(_RI)) - -import core.perms as perms # noqa: E402 -import core.store as store # noqa: E402 -import core.users as users # noqa: E402 -from harness import runtime # noqa: E402 - - -def err(status, code, message): - """The one error shape (X2): non-2xx JSON `{"error": {"code", "message"}}`.""" - return HTTPException(status_code=status, detail={"error": {"code": code, "message": message}}) - - - -def running_main(): - """The `main` module THIS PROCESS IS ACTUALLY RUNNING, or None. Never an `import`. - - ⛔⛔ D-781 — `import main` IN A ROUTE MODULE STARTED A SECOND COPY OF EVERY RESIDENT DAEMON. - The Space runs `uvicorn api.main:app`, so the module executing is `api.main`. Python keys - `sys.modules` by the imported NAME, so a plain `import main` from a route file is a DIFFERENT - module object and **re-executes main.py's whole body** — including its module-level - `threading.Thread(target=_prewarm, …).start()` and `threading.Thread(target=_store_resync_loop, - …).start()`. Two resync loops, two prewarms, in one single-worker container. - - ⛔ AND IT COST REAL MONEY. Staging's own log showed the tell twice over: two `prewarm done` - lines from ONE boot (46.3s and 110.3s, 2026-09-21T11:35:24) and two - `odoo relational rebuild required`/`done` pairs per resync pass, every pass — double the - whole-document Neon reads, on a bill whose entire overage was read egress. - - ⛔⛔ AND THE STATUS ROUTE WAS READING THE SHADOW. `_resync_state` pulled `RESYNC_STATE` from the - duplicate module — a second, separately-populated dict belonging to the second loop — so the - operator surface answering *"is the mirror advancing"* was describing the copy nobody meant to - start. That is the worse half: the cost was invisible and the disclosure was wrong. - - ⚠ IT RESOLVES, IT NEVER IMPORTS, and that restraint is the whole fix: falling back to - `import main` when neither name is loaded would reintroduce exactly the defect. `api.main` - first (uvicorn), then `main` (the gates, which import it under that name) — and None when this - process is running neither, which each caller already handles. - """ - return sys.modules.get("api.main") or sys.modules.get("main") - - -@dataclass -class Session: - """A verified request identity. `user` is the PUBLIC record (never a hash or a salt).""" - tenant: str - user: dict - claims: dict - runtime: object - - @property - def uname(self): - return self.user.get("username", "") - - @property - def admin(self): - return perms.is_admin(self.user) - - def require(self, module_key): - """403 unless this session may open `module_key`. Returns nothing — it is a gate. - - TWO walls, both fail-closed (wave 18, C1-TENANT): the ACCOUNT grant (`perms.may_open`) - and the TENANT catalogue — a registry module a tenant has not enabled is 403 even for - that tenant's admin, or a freshly provisioned Nurilab admin (role=admin ⇒ may_open - everything) would open Royal's Odoo-backed surfaces through any module route. One - chokepoint: `module_gate` and every inline `session.require` pass through here.""" - # ⛔ THE SAME PREDICATE THE NAV USES, or the two disagree and the disagreement is - # invisible: a row the rail offers that the route 403s, or the reverse. The - # editor's explicit grant lands here too, so a database an administrator ticked - # is reachable by URL as well as visible in the rail. - # - # ⭐⭐ W49-T23 / D-612 — `st=self.runtime` IS LOAD-BEARING AND IT WAS MISSING HERE. - # `nav_may_open`'s third leg hands a `ut_*` key to `user_tables.may_open(..., st=st)`, and - # `user_tables._st(None)` falls back to the PROCESS-DEFAULT store — not this caller's - # tenant. So without this argument the wall answered a question about somebody else's - # tenant and happened to be right only while the process default equalled the session - # tenant. `routes_charts._require_database` had already been written with the argument - # (its docstring carries the measurement: a 403 on - # `?database=ut_w39_visual_qa_20260820t214846z` for a user who could read and edit that - # very table through the grid, and a 200 for the identical request once the process - # default happened to match); this is that shape folded back into the one chokepoint, so - # the two can no longer give different answers. - # ⚠ IT WIDENS NOTHING. Threading the session's own runtime makes this ask exactly the - # store the nav rail, `_require_database` and `user_tables.may_open` already ask; every - # answer it can change is one that was previously computed against the wrong tenant. - # The live `ut_*` caller is `routes_grid._pivot_side`, and `grid_pivot` runs - # `perm_scope.pivot_scope(..., st=session.runtime)` over the same key regardless. - import core.perm_scope as _perm_scope - if not _perm_scope.nav_may_open(self.user, module_key, st=self.runtime): - raise err(403, "forbidden", f"your account does not have access to {module_key}") - tcfg = getattr(self.runtime.tenant, "config", None) or {} - tmods = tcfg.get("modules", "all") - if tmods != "all" and str(module_key) not in {str(k) for k in (tmods or [])}: - raise err(403, "forbidden", - f"this workspace does not include {module_key}") - - -# ── Assistant: app-stored, permissioned snapshot boundary (W33-T71 / C8) ─────────────────────── -# -# This is deliberately an ordinary function rather than a route. E owns the Assistant's tool -# routes and model/provider choices; every one of those tools must come through this one boundary -# before it can see a database. Keeping it here gives the reader the already-verified Session and -# prevents Query's schema-only `_target` helper from becoming an accidental data authority. -# -# The important absence is as much part of the contract as the code below: this module never calls -# the Customer/Product pool builders, connector routes, provider routes, Odoo, or an environment -# lookup from this boundary. A cache miss is a named refusal, never permission to refresh from the -# source of truth. That is what "data the app already stores or serves" means in executable form. -# These two keys name registry modules backed by runtime pools. They are DATABASES the product -# may open, but they are not materialised `ut_*` documents and they are not DuckDB read-through -# mirrors. Keeping that distinction in the request boundary prevents a route resolver from -# treating `product_data` as though `_sources()` could bind it to a mirror table. -MODULE_CACHE_DATABASES = { - "customer_data": {"label": "Odoo customers", "cache_prefix": "pool"}, - "product_data": {"label": "Odoo products", "cache_prefix": "product_pool"}, -} -# The Assistant predates the public taxonomy above. Its private name remains an alias so its -# snapshot-only contract and every existing caller stay byte-for-byte unchanged. -_ASSISTANT_BUILT_INS = MODULE_CACHE_DATABASES - - -def module_cache_source(database: str): - """Metadata for a runtime-cache database, or None for every materialised/mirror key.""" - meta = MODULE_CACHE_DATABASES.get(str(database or "")) - return dict(meta) if meta else None - - -def module_cache_rows(session: Session, database: str): - """The current viewer's scoped rows for one known runtime-cache database. - - This is deliberately the interactive grid boundary, not the Assistant snapshot reader: - `scoped_table` applies the same team/agent and row grants as the module page, while - `Session.require` keeps the account and tenant-catalogue checks in their one chokepoint. - Unknown keys fail before either check, so an absent relation target cannot be mislabeled as - a permission denial. - """ - key = str(database or "") - if module_cache_source(key) is None: - raise KeyError(key) - session.require(key) - import core.perm_scope as perm_scope - return list(perm_scope.scoped_table(session.user, key, st=session.runtime) or []) - - -def _assistant_refuse(status, code, message): - """Raise the public error shape without exposing a source implementation detail.""" - raise err(status, code, message) - - -def _assistant_tenant_allows(session: Session, database: str) -> bool: - """Read the served tenant catalogue without reusing the legacy account gate.""" - tenant = getattr(getattr(session, "runtime", None), "tenant", None) - config = getattr(tenant, "config", None) or {} - modules = config.get("modules", "all") if isinstance(config, dict) else "all" - return modules == "all" or str(database) in {str(key) for key in (modules or ())} - - -def _assistant_preflight_request(session: Session, database: str, canonical_fields, - requested_fields, filters, *, require_explicit_grant: bool): - """Refuse an unresolved grant, field or filter before a stored record is touched.""" - import core.perm_scope as perm_scope - - grant = perm_scope.assistant_entry(session.user, database) - if require_explicit_grant and grant is None: - _assistant_refuse(403, "assistant_forbidden", - "your current permissions do not allow this database") - visible = (perm_scope.assistant_visible_fields(canonical_fields, session.user, database) - if grant is not None else list(canonical_fields or ())) - try: - perm_scope.validate_assistant_filter((grant or {}).get("filter"), canonical_fields) - _assistant_requested_fields(requested_fields, visible) - perm_scope.validate_assistant_filter(filters, visible) - except ValueError as exc: - _assistant_refuse(400, "assistant_bad_filter", str(exc)) - return grant, visible - - -def _assistant_cached_builtin(session: Session, database: str, requested_fields=None, filters=None): - """The exact in-process snapshot for one built-in database, or a loud cache-miss refusal. - - This intentionally reads `runtime.pool_cache` directly. Calling either route's `_pool_for` - would make a first Assistant request call Odoo; calling a cache helper would make a stale entry - refresh. Neither is data already stored/served by this process. - """ - import core.perm_scope as perm_scope - - # Unlike an interactive grid, the Assistant has no legacy-grant compatibility path: the - # caller needs a declared, migrated database grant. `may_access` retains the old wall for - # the grid rollout, so it is necessary but not sufficient at this boundary. - declared_access = perm_scope.assistant_entry(session.user, database) is not None - if not _assistant_tenant_allows(session, database) or not declared_access: - _assistant_refuse(403, "assistant_forbidden", - "your current permissions do not allow this database") - - # These are static field contracts, not the route assemblies: route assemblies can add - # per-user workspace state and can call a source builder. The Assistant begins with the - # already-stored base rows only; resolve their grant/field/filter contract *before* the cache - # read so a denied field or malformed operand cannot touch a stored record. - import aios_grid - fields = aios_grid.FIELDS if database == "customer_data" else aios_grid.product_fields() - _assistant_preflight_request(session, database, fields, requested_fields, filters, - require_explicit_grant=True) - - team_id, agent = perm_scope.derive_pool_scope(session.user, database) - cache_key = (("pool", team_id, agent) if database == "customer_data" - else ("product_pool", team_id)) - cache = getattr(session.runtime, "pool_cache", None) - entry = cache.get(cache_key) if isinstance(cache, dict) else None - if (not isinstance(entry, tuple) or len(entry) < 2 - or not isinstance(entry[1], (list, tuple)) - or any(not isinstance(row, dict) for row in entry[1])): - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database has no app-stored snapshot for your current scope") - return list(entry[1]), [dict(field) for field in fields if isinstance(field, dict)], entry[0] - - -#: ⭐⭐ THE TWO WAYS A `ut_*` DATABASE REACHES THE ASSISTANT, AS A SET RATHER THAN AN `or`. -#: Both are walled by `user_tables.may_open` inside their reader, which is why both tolerate a -#: `None` assistant grant at the row/field projection below - and why a THIRD user-table source -#: added later must be added here too or it will be refused for the wrong reason. -_ASSISTANT_USER_TABLE_KINDS = frozenset({"materialised_user_table", "mirror_user_table"}) - - -def _assistant_table_defn(session: Session, database: str): - """The rows-free definition for one `ut_*` database plus its lent runtime, after `may_open`. - - ⛔ THE ROWS-FREE PROJECTION IS THE POINT, not a micro-optimisation. A guessed `ut_*` key must - never make `user_tables.get()` copy the tenant's rows before the table resolver refuses it, - and `all_defs` can fall back to a whole-document read for older stores, so the runtime's - projection primitive is used directly and an absent one fails closed. The existing `may_open` - remains THE resolver; it is lent this rows-dropped document. - - ⭐ FACTORED OUT (W47-T23) because there are now TWO readers behind this one wall - the - materialised document reader and the mirror reader - and `assistant_read_scope` has to know - which of them applies BEFORE it calls either. Reading the projection once and handing the - definition down keeps that dispatch from costing a second store read, and keeps the two - readers from growing two ideas of who may open a database. - """ - from core import user_tables - - try: - definitions = session.runtime.get_projection('user_tables', drop=('rows',)) - except Exception: - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database has no readable definition snapshot") - if not isinstance(definitions, dict): - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database has no readable definition snapshot") - definition = definitions.get(database) - if not isinstance(definition, dict): - _assistant_refuse(404, "assistant_unknown_database", "that database is not available") - definition_runtime = user_tables.lend(session.runtime, user_tables=definitions) - if not user_tables.may_open(database, session.uname, session.admin, st=definition_runtime): - # Deliberately no label/owner in this response: knowing a key must not become an oracle - # for somebody else's database. - _assistant_refuse(403, "assistant_forbidden", - "your current permissions do not allow this database") - return definition, definition_runtime - - -def _assistant_user_table(session: Session, database: str, requested_fields=None, filters=None, - *, defn=None, lent=None): - """Read a materialised user-table document after a rows-free database grant check.""" - from core import user_tables - - definition, _lent = ((defn, lent) if isinstance(defn, dict) - else _assistant_table_defn(session, database)) - - fields = [dict(field) for field in (definition.get("fields") or []) - if isinstance(field, dict) and field.get("key")] - _assistant_preflight_request(session, database, fields, requested_fields, filters, - require_explicit_grant=False) - - # Only an admitted table may now cross the app-stored record seam. This call still has no - # upstream fallback: it is the tenant's materialised document already held by the runtime. - table = user_tables.get(database, st=session.runtime) - if not isinstance(table, dict): - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database changed before its stored snapshot could be read") - if not user_tables.materialises(database, st=session.runtime, defn=table): - # ⭐⭐ W47-T23 / R11 - THIS IS NO LONGER THE ANSWER FOR A MIRROR-SERVED DATABASE, and the - # seam this comment used to ask for now exists: `assistant_mirror.py`, reached through - # `_assistant_mirror_table`. `assistant_read_scope` reads `materialises` off the rows-free - # DEFINITION and dispatches there before this reader is ever entered. - # ⚠ SO WHAT SURVIVES HERE IS A RACE GUARD, NOT A POLICY. It fires only when the definition - # said "materialised" at dispatch and the fetched document says otherwise, i.e. the table - # was un-materialised between the two reads. Returning an empty table would be a false - # answer, so it still refuses; it is simply no longer the ten `ut_odoo_*` grids' fate. - # ⛔ DO NOT "FIX" THIS BY FLIPPING `readThrough`. D-378 says these tables' classification - # is separately wrong; changing the flag to make a read pass would hide that defect and - # move ten grids onto the wrong reader. - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database stopped storing its rows while it was being read; ask " - "again and it will be read from its connector mirror instead") - - # A table's field contract was authorized from the rows-free definition. If it changed while - # the materialised document was fetched, fail rather than projecting a schema that was never - # checked. - actual_fields = [dict(field) for field in (table.get("fields") or []) - if isinstance(field, dict) and field.get("key")] - if actual_fields != fields: - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database changed before its stored snapshot could be read") - raw_rows = table.get("rows") or {} - if not isinstance(raw_rows, dict): - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database does not have a readable stored snapshot") - keys = {field["key"] for field in fields} - rows = [] - for record_id, raw in raw_rows.items(): - if not str(record_id).isdigit() or not isinstance(raw, dict): - continue - # Matches `routes_tables.scoped_pool`: user-table permission is table-level, and only - # declared fields cross this boundary. `pid` is the opaque record identity required to - # bind a returned record to a single-source Query artefact; it is not a selectable field. - rows.append({"pid": int(record_id), - **{key: raw.get(key) for key in keys if key in raw}}) - rows.sort(key=lambda row: row["pid"]) - return rows, fields, (table.get("updated") or table.get("created")), table.get("label") or database - - -def _assistant_mirror_table(session: Session, database: str, requested_fields=None, filters=None, - *, defn=None, lent=None): - """Read a MIRROR-SERVED user table through the same filter compiler the grid uses (R11 / C7). - - Returns `_assistant_user_table`'s 4-tuple - `(rows, fields, source_version, label)` - so the - dispatcher below can swap one for the other and nothing downstream changes. - - ⭐⭐ OWNER R11, VERBATIM: *"Why can't it be queried by the AI if user has access to it? just - query it using our own Filter work. I want the AI to be able to use our tools."* Ten - `ut_odoo_*` databases were offered to the assistant and refused one spent prompt at a time, - because their rows left the tenant document for the DuckDB mirror and this boundary had no - mirror reader. It has one now, and it is the grid's own: `routes_odoo_tables`'s cursor guard, - its column resolver, its window, and `harness.filter_sql`. - - ⛔ THE OPENING IS `_assistant_user_table`'S, DELIBERATELY UNCHANGED - rows-free projection, - `may_open`, `_assistant_preflight_request`. C7: *"the assistant's existing permission - validation"*, reused rather than restated. Only the ROW SOURCE differs. - ⛔ AND IT NEVER CALLS `user_tables.get()`. That whole-document read is precisely what this - path exists to avoid: the rows are not in the document, and fetching 28.6 MB to discover that - is the cost `assistant_permitted_sources` was written to stop paying. - - ⚠ THE FIELD CONTRACT IS `mk_fields()` INTERSECTED WITH THE MIRROR'S COLUMNS, not the stored - `fields`. A declared field with no mirror expression (a link, a rollup) cannot be answered - from SQL, so offering it would return it silently absent; left out, `_assistant_requested_fields` - refuses a request naming it with a loud `assistant_unknown_field`. The preflight therefore - runs against THAT list, so the grant, the wall and the request are all validated against what - can actually be read. - """ - import assistant_mirror - import core.perm_scope as perm_scope - - definition, _lent = ((defn, lent) if isinstance(defn, dict) - else _assistant_table_defn(session, database)) - - # THE CHEAP QUESTION FIRST, and it needs no cursor: is this key a connected Odoo grid at all? - # A `readThrough` table that is not one has no mirror rows anywhere, and asking the mirror - # about it would open a cursor to learn nothing. - if assistant_mirror.declared_fields(database) is None: - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database does not store its rows and it is not one of the " - "connected databases the assistant can read from the mirror") - cur, refusal = assistant_mirror.open_cursor(session) - if refusal is not None: - _assistant_refuse(refusal.status, refusal.code, refusal.message) - spec = assistant_mirror.binding(cur, database) - if spec is None: - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database is served live from its connector and this deployment " - "has no read-through binding for it yet, so it holds no rows to read") - fields = assistant_mirror.answerable_fields(database, spec) - if not fields: - _assistant_refuse(409, "assistant_snapshot_unavailable", - "this database's connector mirror carries none of its declared columns " - "on this deployment, so there is nothing to answer from") - - grant, visible = _assistant_preflight_request(session, database, fields, requested_fields, - filters, require_explicit_grant=False) - - # ⛔ COMPILE THE **VALIDATED** TREES, NEVER THE RAW ONES, and this is what makes the done-when - # structural rather than lucky. `assistant_read_scope` runs `filter_eval.permits` over - # `validate_assistant_filter`'s RETURN, and `assistant_apply_row_scope` over the grant's tree. - # Pushing the raw input to SQL instead would mean the pushdown and the Python pass are two - # predicates that happen to agree, which is this repo's recorded defect class. Same input to - # both compilers, same answer by construction. - try: - wall_tree = perm_scope.validate_assistant_filter((grant or {}).get("filter"), fields) - filter_tree = perm_scope.validate_assistant_filter(filters, visible) - except ValueError as exc: - _assistant_refuse(400, "assistant_bad_filter", str(exc)) - raise # unreachable; keeps the names bound for a reader - # ⚠ NO GRANT MEANS NO ROW WALL ON THIS PATH, matching `assistant_read_scope` exactly: it - # applies `assistant_apply_row_scope` only when a grant resolved, because `may_open` above is - # what admitted a user table. Pushing a wall down that Python will not apply would narrow the - # answer below what the caller is entitled to, which is a wrong number in the other direction. - if grant is None: - wall_tree = None - - try: - rows, stamp, total = assistant_mirror.read_rows( - session, database, cur, spec, fields, - wall_tree=wall_tree, filter_tree=filter_tree, - filter_keys=[field["key"] for field in visible - if isinstance(field, dict) and field.get("key")]) - except assistant_mirror.MirrorRefusal as exc: - _assistant_refuse(exc.status, exc.code, exc.message) - raise # unreachable; see above - - # ⭐ PROVENANCE A CITATION CAN CARRY. `routes_query._system_prompt` runs - # `json.dumps(source_version, default=str)`, so this stays plain JSON: when the mirror last - # reconciled this table against its connector, and how many rows the answer was computed over. - # The count is here because the model is told the record count separately, and a reader - # checking one against the other should find the same integer. - source_version = {"read": "connector mirror", "refreshed": stamp, "rows": total} - return rows, fields, source_version, definition.get("label") or database - - -def _assistant_requested_fields(fields, visible_fields): - """Resolve an explicit field selection without turning an unknown key into an omission.""" - by_key = {str(field.get("key")): field for field in visible_fields - if isinstance(field, dict) and field.get("key")} - if fields is None: - return list(by_key) - if not isinstance(fields, (list, tuple)): - _assistant_refuse(400, "assistant_bad_fields", "fields must be a list of field keys") - out = [] - for raw in fields: - key = raw.strip() if isinstance(raw, str) else "" - if not key or key not in by_key or key in out: - _assistant_refuse(400, "assistant_unknown_field", - "every requested field must be visible in this database") - out.append(key) - return out - - -def assistant_read_scope(session: Session, database, fields=None, filters=None): - """Return a detached, permissioned snapshot for one Assistant tool call. - - Signature (the C8 contract for E): - assistant_read_scope(session, database, fields, filters) -> { - database, label, source_kind, source_version, retrieved_at, - permission_scope_applied, fields, filters, records - } - - `database` is exactly one source. `fields` is an explicit list of visible field keys (or - ``None`` for every visible field). `filters` is ``None`` or the strict tree accepted by - `core.perm_scope.validate_assistant_filter`; it rejects unknown, hidden, inactive and - unsupported operands before a row is read. The returned dictionaries are deep copies, never - a live cache/store object, cursor, connector, route, provider, or credential. - """ - import core.perm_scope as perm_scope - from harness import filter_eval - - key = str(database or "").strip() - if key in _ASSISTANT_BUILT_INS: - rows, canonical_fields, source_version = _assistant_cached_builtin(session, key, fields, filters) - label = _ASSISTANT_BUILT_INS[key]["label"] - source_kind = "runtime_cache" - elif key.startswith("ut_"): - # ⭐⭐ W47-T23 / R11 - TWO READERS BEHIND ONE WALL, CHOSEN OFF THE ROWS-FREE DEFINITION. - # `_assistant_table_defn` is read ONCE here and lent to whichever reader applies, so the - # dispatch costs no extra store read and the two readers cannot grow two ideas of who may - # open a database. `materialises` is the FIRST of the two predicates - # `assistant_source_status` reports `answerable` from, and the mirror binding is the - # second, so the picker and the reader admit the same set by construction. - # ⛔ THE FLAG IS READ, NEVER WRITTEN. D-378 says these tables' `readThrough` classification - # is separately wrong; the fix for that is not to reclassify them here so a read passes. - from core import user_tables - _defn, _lent = _assistant_table_defn(session, key) - if user_tables.materialises(key, st=_lent, defn=_defn): - rows, canonical_fields, source_version, label = _assistant_user_table( - session, key, fields, filters, defn=_defn, lent=_lent) - source_kind = "materialised_user_table" - else: - rows, canonical_fields, source_version, label = _assistant_mirror_table( - session, key, fields, filters, defn=_defn, lent=_lent) - source_kind = "mirror_user_table" - else: - _assistant_refuse(404, "assistant_unknown_database", "that database is not available") - - # Permanent permissions run against the full source contract. A permission filter may name - # a field that is intentionally hidden from the returned schema; resolving it after the field - # projection would make that filter unanswerable and (depending on the evaluator) could widen. - # Validate even that grant before evaluating it: `permits` would deny an unknown operand row - # by row, but the Assistant contract requires an explicit refusal for unresolved grants. - grant = perm_scope.assistant_entry(session.user, key) - if source_kind not in _ASSISTANT_USER_TABLE_KINDS and grant is None: - # `_assistant_cached_builtin` already made this decision before touching its cache. Keep - # this guard adjacent to the field/row projection so a future source cannot forget it. - # ⚠ A SET, NOT AN `or`, AND BOTH USER-TABLE KINDS ARE IN IT (W47-T23). Either reader has - # already passed `user_tables.may_open`, which is the wall for that family; requiring a - # SECOND, assistant-specific grant here would refuse a table the user demonstrably holds. - # Spelled as membership so a third user-table source is one line, not a growing chain. - _assistant_refuse(403, "assistant_forbidden", - "your current permissions do not allow this database") - try: - perm_scope.validate_assistant_filter((grant or {}).get("filter"), canonical_fields) - except ValueError as exc: - _assistant_refuse(400, "assistant_bad_filter", str(exc)) - # ⭐ OWNER I16 — the tenant handle rides into the row wall here too, so one stored rule means - # the same thing in the Analyst's answer as it does on the grid (see - # `perm_scope._enrich_for_wall`). - # - # ⚠ AND IT CHANGES NOTHING ON THIS PATH TODAY, WHICH IS STATED RATHER THAN LEFT TO BE - # REDISCOVERED. `validate_assistant_filter` three lines up refuses any leaf naming a column - # outside `canonical_fields`, so a wall on a user-generated column is rejected before it can - # reach this call at all. The handle is passed anyway because the alternative is a door that - # walls these modules WITHOUT it — and "all six or none" is the property that keeps one wall - # from having two meanings. Widening the Assistant's own validator to admit such a column is - # a separate decision about what E may read, not a side effect of a grid fix. - permitted_rows = (perm_scope.assistant_apply_row_scope(rows, session.user, key, - canonical_fields, - st=getattr(session, "runtime", None)) - if grant is not None else list(rows or ())) - visible = (perm_scope.assistant_visible_fields(canonical_fields, session.user, key) - if grant is not None else list(canonical_fields)) - selected_keys = _assistant_requested_fields(fields, visible) - try: - requested_filter = perm_scope.validate_assistant_filter(filters, visible) - except ValueError as exc: - _assistant_refuse(400, "assistant_bad_filter", str(exc)) - if requested_filter is not None: - permitted_rows = [row for row in permitted_rows - if filter_eval.permits(requested_filter, row, visible)] - - records = [] - for row in permitted_rows: - if not isinstance(row, dict) or row.get("pid") is None: - continue - records.append({"pid": copy.deepcopy(row["pid"]), - **{field: copy.deepcopy(row.get(field)) for field in selected_keys}}) - - return { - "database": key, - "label": str(label), - "source_kind": source_kind, - "source_version": copy.deepcopy(source_version), - "retrieved_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), - "permission_scope_applied": True, - "fields": [copy.deepcopy(field) for field in visible - if field.get("key") in selected_keys], - "filters": copy.deepcopy(requested_filter), - "records": records, - } - - -def assistant_permitted_sources(session: Session, databases): - """Which of `databases` the caller may still read — WITHOUT reading one record. - - ⛔ THIS EXISTS BECAUSE `GET /query` LISTS ARTEFACTS, AND AN ARTEFACT IS NOT A READ. - `routes_query._public_state` has to drop every saved view whose source the caller has since - lost. The obvious way to ask that question is `assistant_read_scope(..., fields=[])` — and it - is the wrong one: for a `ut_*` source that call runs `user_tables.get()`, i.e. a WHOLE-DOCUMENT - read of the tenant store (measured at **28.6 MB / 703 ms warm on tenant #0**, and 99.9% of those - bytes are `rows` this question does not look at), then projects every row down to its `pid` and - throws the result away. Once per saved view, up to `MAX_ARTIFACTS = 200` of them, on a route - that BOTH the Assistant and Query call on mount. That is `/nav`'s old 1+N whole-document read - (D-175, an 11.0 s median) rebuilt inside a new route, and every fixture with two artefacts - passes it [[measure-the-real-call]]. - - So this asks the permission question and ONLY the permission question: - * the rows-free `user_tables` projection is read at most ONCE for the whole batch, and lent - to `may_open` exactly as `_assistant_user_table` lends it; - * a built-in resolves from the tenant catalogue and the declared grant, with no `pool_cache` - read — a cache MISS is a data-availability fact, not a permission one, and refusing to list - an artefact because its snapshot is cold would silently delete the user's history from the - rail every time the process restarted [[empty-answer-vs-unfinished-answer]]. - - ⚠ It is deliberately NOT a second permission wall. Every predicate here is the same call - `assistant_read_scope` makes for the same source; nothing may be admitted here that the read - boundary would refuse, which is what `verify_query.py` asserts in both directions. - """ - return {key for key, row in assistant_source_status(session, databases).items() - if row["permitted"]} - - -def assistant_source_status(session: Session, databases=None): - """`{key: {permitted, answerable, reason}}` — WITHOUT reading one record. - - ⭐⭐ `answerable` EXISTS BECAUSE `permitted` IS NOT THE QUESTION THE READER IS ASKING. - Measured on tenant #0, signed in, 2026-08-15: the Assistant offered **twelve** source chips - and could answer for **two**. The other ten are the `ut_odoo_*` grids, and - `_assistant_user_table` refused every one of them because their rows live UNCAPPED in the - DuckDB mirror and are read through it (W30/R6 is exactly why). The refusal was correct, named - and fail-closed. The defect was that it arrived one spent prompt at a time: a picker that - offers ten doors which cannot open is the same shape as the rail that painted two rows - differently from five. - ⚠ It is R6's SECOND SENTENCE, in the family that rule was written for — a limit that cannot be - removed must be REPORTED with its cause, never silently enforced. - - ⭐⭐ W47-T23 / OWNER R11 — **THE LIMIT IS NOW CLOSED, NOT EXPLAINED**, so `answerable` has TWO - ways to be true. Owner: *"Why can't it be queried by the AI if user has access to it? just - query it using our own Filter work. I want the AI to be able to use our tools."* A `ut_*` - database is answerable when it materialises OR when this deployment has a read-through - binding for it, because `_assistant_mirror_table` reads that binding through the same filter - compiler the grid uses. MEASURED on this worktree, all eight connected grids declared - read-through: **four answerable** (`ut_odoo_accounts`, `ut_odoo_gl_lines`, - `ut_odoo_order_lines`, `ut_odoo_orders`), four still reported with their cause, which is that - this deployment's mirror carries no table behind them. - - ⛔ IT NO LONGER COSTS NOTHING, AND THE PRICE IS STATED RATHER THAN LEFT TO BE FOUND. - `user_tables.materialises()` reads the `readThrough` flag off the DEFINITION the rows-free - projection already carries, so the first predicate is still free. The second needs the mirror. - MEASURED warm, median of five, whole batch of ten sources on this worktree: **0.5 ms before, - 15.6 ms after (+15.1 ms)**, using ONE cursor for the batch and `assistant_mirror.is_bound` - rather than a full spec resolve. The full resolve was tried FIRST and measured **+605 ms**, - because `_source_for` runs `excluded_ids`, a scan of every partner row, once per grid; - `is_bound`'s docstring carries that measurement and the reason it is safe to stop short of it. - - ⚠ `databases=None` enumerates every source this tenant HAS (the two built-ins plus every - `ut_*` in the projection) rather than taking a caller-supplied list. A client list would make - the answer depend on what the caller thought to ask about, and the nav has already told them - what they hold. - """ - import core.perm_scope as perm_scope - from core import user_tables - - definitions = None - read_definitions = False - mirror_cur = None - read_mirror = False - - def _mirror(): - """The batch's ONE mirror cursor, opened lazily, or None. Never raises. - - ⭐⭐ W47-T23 - `answerable` NOW HAS A SECOND WAY TO BE TRUE, because the assistant can - read a mirror-served database (R11). A table that does not materialise is answerable when - this deployment has a read-through binding for it, so this batch has to ask the mirror. - ⛔ AT MOST ONE CURSOR, AND ONLY WHEN SOMETHING NEEDS IT. `databases=None` enumerates every - source the tenant has, and this function is called on mount by both the Assistant and - Query; a cursor per key, or a cursor on a tenant with no read-through tables at all, would - put a mirror open on the hot path of a route that used to touch one projection. Opened on - first need, reused for the rest of the batch, closed by the process as before. - ⚠ FAIL-QUIET TO `None`, unlike the READ path. This function reports availability; if the - mirror cannot be opened, the honest answer is "not answerable yet, and here is why", - which is the branch below. A raise here would take down the whole picker over one source. - """ - nonlocal mirror_cur, read_mirror - if not read_mirror: - read_mirror = True - try: - import assistant_mirror - cur, refusal = assistant_mirror.open_cursor(session) - mirror_cur = None if refusal is not None else cur - except Exception: # noqa: BLE001 - mirror_cur = None - return mirror_cur - - def _definitions(): - nonlocal definitions, read_definitions - if not read_definitions: - read_definitions = True - try: - candidate = session.runtime.get_projection('user_tables', drop=('rows',)) - except Exception: - candidate = None - definitions = candidate if isinstance(candidate, dict) else None - return definitions - - if databases is None: - wanted = list(_ASSISTANT_BUILT_INS) + [ - key for key in sorted((_definitions() or {})) - if isinstance(key, str) and key.startswith("ut_") - ] - else: - wanted = [str(key or "").strip() for key in (databases or ())] - wanted = list(dict.fromkeys(key for key in wanted if key)) - - out = {} - for key in wanted: - # `visible` = "the caller can open this database elsewhere in the product". D-276 uses it - # to decide whether an unusable source is REPORTED or stays absent; default False, so a - # branch that never sets it keeps today's silence rather than inheriting a disclosure. - row = {"permitted": False, "answerable": False, "reason": "", "visible": False} - out[key] = row - if key in _ASSISTANT_BUILT_INS: - # ⭐⭐ D-276 (2026-08-15) — AN OMISSION MUST STATE ITS CAUSE, and this branch used to - # `continue` in silence. MEASURED on tenant #0, both `admin` and `leadership`: - # `GET /query` listed nine sources and `product_data` was not among them, while - # `POST /query/chat {database:"product_data"}` answered 403 `assistant_forbidden` — - # for a database the SAME account opens from the nav, holds saved views on, and can - # see in the Database flyout. The mirror-served grids were un-askable too and they - # WERE listed, with their cause in the chip; this one said nothing at all. (W47-T23 - # has since made those grids readable, so the contrast is now with the four whose - # mirror table this deployment does not carry; the asymmetry this branch fixes is - # unchanged.) - # ⛔ THE ASYMMETRY IS THE DEFECT, NOT THE REFUSAL. R6's second sentence: a limit that - # cannot be removed must be REPORTED with its cause, never silently enforced. - # ⚠ `visible` IS WHAT KEEPS THIS FROM BEING A DISCLOSURE. A source the caller cannot - # open ANYWHERE stays absent — naming it would tell them a database exists that they - # were never allowed to know about. `visible` is true only when the ordinary product - # wall already lets them open it, i.e. when the silence was incoherent rather than - # protective. `permitted` is untouched: it gates which stored artefacts survive, and - # widening it here would resurrect views the read boundary refuses. - if not _assistant_tenant_allows(session, key): - row["visible"] = bool(perm_scope.may_access(session.user, key)) - row["reason"] = ("this workspace's catalogue does not list it as an assistant " - "source. An administrator can add it") - continue - if perm_scope.assistant_entry(session.user, key) is None: - row["visible"] = bool(perm_scope.may_access(session.user, key)) - # ⛔⛔ THIS SENTENCE DELIBERATELY PROMISES NO REMEDY, AND THAT IS A CORRECTION. - # Its first version said *"an administrator can re-save them"*. MEASURED on the - # deployed build the same hour: re-saving `leadership`'s permissions through - # `PUT /admin/users/{u}/perms` returned 200 with the block byte-identical and - # `perms_v` unchanged at 1 — and the source stayed refused. So the advice was - # wrong, and a refusal that hands the reader a fix which does not work is worse - # than one that admits it does not know: they spend the trip and land back here. - # ⚠ The cause is still open (D-276). `assistant_entry` reads only `entry`, - # `is_migrated` and `may_access`, and `product_data` carries the SAME grant as - # `customer_data` under one record — so the divergence is not visible in the perms - # document and guessing at it once already produced a wrong answer. - row["reason"] = ("the assistant cannot resolve a data grant for it yet. This is a " - "known gap (D-276), not something you have set wrongly") - continue - row["permitted"] = True - # ⚠ A CACHE MISS IS A DATA-AVAILABILITY FACT, NOT A PERMISSION ONE, and it must not - # drop the source from the list — an artefact already built on it stays listed. It is - # reported as not-yet-answerable, with the action that fixes it. MEASURED: the pool is - # filled by a grid REQUEST, not by `AIOS_PREWARM` — a fresh process refuses until - # somebody opens the database once. - team_id, agent = perm_scope.derive_pool_scope(session.user, key) - cache_key = (("pool", team_id, agent) if key == "customer_data" - else ("product_pool", team_id)) - cache = getattr(session.runtime, "pool_cache", None) - entry = cache.get(cache_key) if isinstance(cache, dict) else None - if isinstance(entry, tuple) and len(entry) >= 2 and isinstance(entry[1], (list, tuple)): - row["answerable"] = True - else: - row["reason"] = "no snapshot loaded yet. Open this database once, then ask" - continue - if not key.startswith("ut_"): - continue - defs = _definitions() - definition = (defs or {}).get(key) - if not isinstance(definition, dict): - continue - lent = user_tables.lend(session.runtime, user_tables=defs) - if not user_tables.may_open(key, session.uname, session.admin, st=lent): - continue - row["permitted"] = True - if user_tables.materialises(key, st=lent, defn=definition): - row["answerable"] = True - continue - # ⭐⭐ W47-T23 / R11 - THE SECOND WAY TO BE ANSWERABLE. This used to end here with a flat - # "the assistant cannot read it yet", which was true of every mirror-served grid and is - # now true of none that this deployment binds. `_assistant_mirror_table` reads them - # through the same filter compiler the grid uses, so the picker must stop saying they are - # shut. - # ⛔ THE REASON STILL HAS TO NAME ITS CAUSE (R6's second sentence), and the two remaining - # causes are DIFFERENT causes with different fixes: a mirror that cannot be opened at all - # is transient and retrying works, while a grid this deployment has no read-through - # binding for will not fix itself by waiting. One sentence for both would make the first - # look permanent, which is the failure mode the ruling exists to prevent. - cur = _mirror() - if cur is None: - row["reason"] = ("this database is read live from its connector mirror, and that " - "mirror is not open on this deployment right now; try again shortly") - continue - # ⛔ `is_bound`, NOT `binding` - THE AVAILABILITY QUESTION, NOT THE READ ONE, and the - # difference is 300 ms PER KEY here. Resolving a full spec runs `excluded_ids`, a scan of - # every partner row, for three of this tenant's grids; measured, it put +605 ms on this - # batch, which is called on mount by both the Assistant and Query. See `is_bound`. - try: - import assistant_mirror - bound = assistant_mirror.is_bound(cur, key) - except Exception: # noqa: BLE001 - bound = False - if bound: - row["answerable"] = True - else: - row["reason"] = ("this database is read live from its connector mirror, and this " - "deployment has no read-through binding for it yet, so it holds no " - "rows the assistant can read") - return out - - -def _user_for(claims): - """The account named by a verified cookie, or None — with the epoch check that makes a - stateless cookie revocable. - - ⛔ THE RULE THIS FUNCTION MUST OBEY: **it has to accept exactly the identities the login route - issues.** Any divergence produces the worst failure shape there is — a login that returns 200 - with a cookie and then 401s every request after it. - - TWO CASES: - * THE RECORD, if it is readable and satisfies everything a session adds on top of a login: - the account is active, and its CURRENT epoch equals the cookie's — otherwise the session - is revoked (a password change or a deactivation bumped it). - * THE QA RUNNER, only when both non-production deployment gates remain enabled and its - password-derived epoch still matches. Live deployments cannot enable it. - * anything else → None. An unknown username is NOT admitted just because its signature was - valid: a signature proves the cookie is ours, not that the account still exists. - """ - uname = (claims.get("u") or "").strip().lower() - if not uname: - return None - claim_tenant = str(claims.get("t") or "").strip().lower() - # W39-T28 / A62. This MUST precede the registry read: qa-runner is specifically a - # zero-touch qa-b identity, not an account in tenant #0's `users` document. The helper - # rechecks both non-production deployment flags, so removing either invalidates its cookie. - qa = users.qa_identity(uname) - if (qa and claim_tenant == qa.get("tenant") - and int(claims.get("e") or 0) == int(qa.get("epoch") or 0)): - return qa - try: - reg = users.registry() or {} - except Exception: - reg = {} - rec = reg.get(uname) - if (rec and rec.get("active", True) - and int(rec.get("epoch") or 0) == int(claims.get("e") or 0)): - pub = users._public(uname, rec) - # ⛔ Wave 18 (C1-TENANT, R1): the cookie's tenant must be THE ACCOUNT'S tenant. Before - # this line, any valid credential could mint a session for any registered slug - # (login validated the slug's existence, never the membership) — with - # AIOS_ENABLE_QA_TENANT=1 that was a working cross-tenant session. A signature proves - # the cookie is ours; THIS proves the account belongs where the cookie says it does. - # ⚠ WAVE 33 (W33-T37) — the default was DELETED, not changed. It read - # `pub.get("tenant", "royal-imports")` and could never fire: `users._public` normalises a - # missing tenant to `royal-imports` before this line ever sees it. A dead default that - # names a real tenant reads like a live fallback, and the cross-tenant audit spent a row - # proving it was not one. Bare `.get` is also the safer shape if that ever stops being - # true: `None != claim_tenant` denies, where the old default would have ADMITTED a - # tenant-less record into tenant #0's session. - if claim_tenant != pub.get("tenant"): - return None - return pub - return None - - -# --- wave 19 (R4): the LAST-ACTIVE stamp, throttled in this process ------------------------------ -# "Is anyone actually using this account?" is one of the two questions the Loopable admin plane -# answers, and the only place that can honestly answer it is the session resolver — every -# authenticated request passes through here. -# -# ⛔ THEREFORE IT MUST COST ALMOST NOTHING. A store write per request would put the HF store's -# 256-commits/hour budget on the critical path of the entire API, and a store READ per request to -# decide whether to write would be little better. So the staleness decision is made from a -# PROCESS-LOCAL map: no I/O at all on the 99.97% of requests inside the window, and the write -# itself (once an hour per account) happens on `core.users`' own background thread, so no request -# ever waits for a hub round-trip. `core.users` explains why that write is SYNC and not the -# coalesced async path — `users.json` is shared with the Streamlit host and an async flush rebases -# on this process's cache, which would let a stamp revert somebody else's deactivation. -# -# HONEST LIMITS, stated rather than discovered later: the map is per-process, so N workers can each -# write once per window (still bounded); a restart re-arms every user's first request; and the -# resolution of `last_active` is therefore "within the last hour", which is exactly what the plane -# renders it as. Bounded independently so it cannot grow into a leak on a deployment -# with many accounts. -_ACTIVE_SEEN: "OrderedDict[str, float]" = OrderedDict() -_ACTIVE_EVERY = float(os.environ.get("AIOS_ACTIVE_STAMP_SECONDS") or 3600) -_ACTIVE_MAX_TRACKED = 4096 - -#: ⚠ MUST MATCH `web/src/apiContract.ts::TENANT_HEADER` EXACTLY — the client compares this -#: header against the tenant its frame booted with, and a rename on one side alone turns the -#: guard OFF silently (an absent header reads as "no change", by design, so nothing would go -#: red). `verify_wiring.py` pins both spellings for that reason. -_TENANT_HEADER = "X-AIOS-Tenant" - - -def note_active(uname, when=None): - """Record that `uname` was just seen — WITHOUT writing. The login path calls this because it - has already stamped `last_active` itself; without it the very next request would find no entry - and stamp again immediately, making the "at most once an hour" rule false by one write per - sign-in.""" - key = (uname or "").strip().lower() - if not key: - return - _ACTIVE_SEEN[key] = when if when is not None else time.time() - _ACTIVE_SEEN.move_to_end(key) - while len(_ACTIVE_SEEN) > _ACTIVE_MAX_TRACKED: - _ACTIVE_SEEN.popitem(last=False) - - -def _touch_active(uname): - """Stamp `last_active` at most once per window per account, per process. Never raises.""" - try: - key = (uname or "").strip().lower() - if not key: - return - now = time.time() - last = _ACTIVE_SEEN.get(key) - if last is not None and (now - last) < _ACTIVE_EVERY: - return - note_active(key, now) - users.touch_active(key) - except Exception: # noqa: BLE001 — telemetry may never break a request - pass - - -def require_session(request: Request, response: Response) -> Session: - """Verify the cookie, resolve the tenant, and REISSUE the cookie (the 8h idle window is - refreshed on use; the 30-day absolute expiry is carried over, never extended).""" - raw = request.cookies.get(aios_session.COOKIE_NAME) - if not raw: - raise err(401, "no_session", "sign in to continue") - claims = aios_session.read(raw) - if not claims: - raise err(401, "invalid_session", "your session has expired. Sign in again") - user = _user_for(claims) - if not user: - raise err(401, "invalid_session", "your session has expired. Sign in again") - try: - rt = runtime.get_runtime(claims["t"]) - except KeyError: - # An unknown tenant slug is a 401, not a 404: the cookie is not a valid identity for this - # deployment, and confirming which slugs exist would answer a question we were not asked. - raise err(401, "invalid_session", "your session has expired. Sign in again") - fresh, _ = aios_session.mint(claims["t"], user["username"], int(user.get("epoch") or 0), - absolute_expiry=claims["x"]) - aios_session.set_cookie(response, request, fresh) - # ⭐ STAMP THE TENANT THIS ANSWER WAS SERVED FOR (owner report 2026-08-09: "I can see - # Nurilab's automations when logged into Royal Imports"). - # - # ⛔ THE SERVER WAS NEVER WRONG — MEASURED, link by link: per-tenant dataset repos, - # `get_runtime(claims["t"])` off the SIGNED cookie, and the `claim_tenant != pub["tenant"]` - # refusal above. The browser is what blends them: `aios_session` is ONE cookie at `path="/"` - # per ORIGIN, so signing into tenant B in a second tab silently repoints the FIRST tab. That - # tab goes on painting tenant A's chrome while every new request is answered for tenant B — - # and a WRITE from it lands in tenant B's store, which is the same event reported separately - # as "I updated the data and it doesn't register". - # - # It is stamped HERE rather than in a middleware because this is the one function every - # session-authed route passes through, so no route can be added that forgets it — and it is - # the only place that has already RESOLVED the tenant rather than guessed it. - # ⚠ The value is `claims["t"]`, the tenant the cookie was VERIFIED for — never - # `session.tenant` read back from something the request could influence. - response.headers[_TENANT_HEADER] = str(claims["t"]) - # R4: last AFTER the session is fully resolved — a stamp is only true of a request that was - # actually admitted, and putting it here means no failed-auth path can ever write one. - # qa-runner has no global account record. Never let the normal activity telemetry create or - # touch one through the default tenant-#0 users store. - if not user.get("qa_runner"): - _touch_active(user.get("username")) - return Session(tenant=claims["t"], user=user, claims=claims, runtime=rt) - - -def require_changes_session(request: Request, response: Response) -> Session | None: - """Authenticate the passive Pg change endpoint without reopening the database. - - Pg change tokens are intentionally disabled: a current client refreshes the data it is viewing - on focus, while an already-open legacy client may still call this route every ten seconds. A - verified signed cookie is enough to return that no-data response; resolving the account record - would itself turn those legacy requests into a permanent Neon keepalive. - """ - if store.backend() != "pg": - return require_session(request, response) - if request.headers.get("x-aios-change-check") == "focus-v1": - return require_session(request, response) - raw = request.cookies.get(aios_session.COOKIE_NAME) - claims = aios_session.read(raw) if raw else None - if not claims or not str(claims.get("t") or "").strip() or not str(claims.get("u") or "").strip(): - raise err(401, "invalid_session", "your session has expired. Sign in again") - return None - - -def module_gate(module_key): - """A dependency that 401s without a session and 403s without the grant for `module_key`.""" - def _dep(session: Session = Depends(require_session)) -> Session: - session.require(module_key) - return session - return _dep +"""deps.py — the request-scoped session + tenant resolution every v1 route depends on. + +ONE place answers "who is asking, for which tenant, and what may they see?", because a +permission check that exists in four routes has four chances to be forgotten. The routes take +`session: Session = Depends(require_session)` and receive an object that has ALREADY failed +closed if anything was wrong. + +FAIL-CLOSED, spelled out (X2): no cookie → **401**. Cookie present but unverifiable, expired, +epoch-revoked, or naming an unknown tenant → **401**. Authenticated but not granted the surface → +**403**. Never an empty 200: an empty list is a legitimate answer meaning "no rows", and using it +to mean "you are not allowed" is how a permission bug becomes invisible. +""" +import copy +import os +import sys +import time +from collections import OrderedDict +from dataclasses import dataclass +from pathlib import Path + +from fastapi import Depends, HTTPException, Request, Response + +import aios_session + +_RI = Path(os.environ.get("RI_DIR") or Path(__file__).resolve().parents[2] / "platform") +if str(_RI) not in sys.path: + sys.path.insert(0, str(_RI)) + +import core.perms as perms # noqa: E402 +import core.store as store # noqa: E402 +import core.users as users # noqa: E402 +from harness import runtime # noqa: E402 + + +def err(status, code, message): + """The one error shape (X2): non-2xx JSON `{"error": {"code", "message"}}`.""" + return HTTPException(status_code=status, detail={"error": {"code": code, "message": message}}) + + + +def running_main(): + """The `main` module THIS PROCESS IS ACTUALLY RUNNING, or None. Never an `import`. + + ⛔⛔ D-781 — `import main` IN A ROUTE MODULE STARTED A SECOND COPY OF EVERY RESIDENT DAEMON. + The Space runs `uvicorn api.main:app`, so the module executing is `api.main`. Python keys + `sys.modules` by the imported NAME, so a plain `import main` from a route file is a DIFFERENT + module object and **re-executes main.py's whole body** — including its module-level + `threading.Thread(target=_prewarm, …).start()` and `threading.Thread(target=_store_resync_loop, + …).start()`. Two resync loops, two prewarms, in one single-worker container. + + ⛔ AND IT COST REAL MONEY. Staging's own log showed the tell twice over: two `prewarm done` + lines from ONE boot (46.3s and 110.3s, 2026-09-21T11:35:24) and two + `odoo relational rebuild required`/`done` pairs per resync pass, every pass — double the + whole-document Neon reads, on a bill whose entire overage was read egress. + + ⛔⛔ AND THE STATUS ROUTE WAS READING THE SHADOW. `_resync_state` pulled `RESYNC_STATE` from the + duplicate module — a second, separately-populated dict belonging to the second loop — so the + operator surface answering *"is the mirror advancing"* was describing the copy nobody meant to + start. That is the worse half: the cost was invisible and the disclosure was wrong. + + ⚠ IT RESOLVES, IT NEVER IMPORTS, and that restraint is the whole fix: falling back to + `import main` when neither name is loaded would reintroduce exactly the defect. `api.main` + first (uvicorn), then `main` (the gates, which import it under that name) — and None when this + process is running neither, which each caller already handles. + """ + return sys.modules.get("api.main") or sys.modules.get("main") + + +@dataclass +class Session: + """A verified request identity. `user` is the PUBLIC record (never a hash or a salt).""" + tenant: str + user: dict + claims: dict + runtime: object + + @property + def uname(self): + return self.user.get("username", "") + + @property + def admin(self): + return perms.is_admin(self.user) + + def require(self, module_key): + """403 unless this session may open `module_key`. Returns nothing — it is a gate. + + TWO walls, both fail-closed (wave 18, C1-TENANT): the ACCOUNT grant (`perms.may_open`) + and the TENANT catalogue — a registry module a tenant has not enabled is 403 even for + that tenant's admin, or a freshly provisioned Nurilab admin (role=admin ⇒ may_open + everything) would open Royal's Odoo-backed surfaces through any module route. One + chokepoint: `module_gate` and every inline `session.require` pass through here.""" + # ⛔ THE SAME PREDICATE THE NAV USES, or the two disagree and the disagreement is + # invisible: a row the rail offers that the route 403s, or the reverse. The + # editor's explicit grant lands here too, so a database an administrator ticked + # is reachable by URL as well as visible in the rail. + # + # ⭐⭐ W49-T23 / D-612 — `st=self.runtime` IS LOAD-BEARING AND IT WAS MISSING HERE. + # `nav_may_open`'s third leg hands a `ut_*` key to `user_tables.may_open(..., st=st)`, and + # `user_tables._st(None)` falls back to the PROCESS-DEFAULT store — not this caller's + # tenant. So without this argument the wall answered a question about somebody else's + # tenant and happened to be right only while the process default equalled the session + # tenant. `routes_charts._require_database` had already been written with the argument + # (its docstring carries the measurement: a 403 on + # `?database=ut_w39_visual_qa_20260820t214846z` for a user who could read and edit that + # very table through the grid, and a 200 for the identical request once the process + # default happened to match); this is that shape folded back into the one chokepoint, so + # the two can no longer give different answers. + # ⚠ IT WIDENS NOTHING. Threading the session's own runtime makes this ask exactly the + # store the nav rail, `_require_database` and `user_tables.may_open` already ask; every + # answer it can change is one that was previously computed against the wrong tenant. + # The live `ut_*` caller is `routes_grid._pivot_side`, and `grid_pivot` runs + # `perm_scope.pivot_scope(..., st=session.runtime)` over the same key regardless. + import core.perm_scope as _perm_scope + if not _perm_scope.nav_may_open(self.user, module_key, st=self.runtime): + raise err(403, "forbidden", f"your account does not have access to {module_key}") + tcfg = getattr(self.runtime.tenant, "config", None) or {} + tmods = tcfg.get("modules", "all") + if tmods != "all" and str(module_key) not in {str(k) for k in (tmods or [])}: + raise err(403, "forbidden", + f"this workspace does not include {module_key}") + + +# ── Assistant: app-stored, permissioned snapshot boundary (W33-T71 / C8) ─────────────────────── +# +# This is deliberately an ordinary function rather than a route. E owns the Assistant's tool +# routes and model/provider choices; every one of those tools must come through this one boundary +# before it can see a database. Keeping it here gives the reader the already-verified Session and +# prevents Query's schema-only `_target` helper from becoming an accidental data authority. +# +# The important absence is as much part of the contract as the code below: this module never calls +# the Customer/Product pool builders, connector routes, provider routes, Odoo, or an environment +# lookup from this boundary. A cache miss is a named refusal, never permission to refresh from the +# source of truth. That is what "data the app already stores or serves" means in executable form. +# These two keys name registry modules backed by runtime pools. They are DATABASES the product +# may open, but they are not materialised `ut_*` documents and they are not DuckDB read-through +# mirrors. Keeping that distinction in the request boundary prevents a route resolver from +# treating `product_data` as though `_sources()` could bind it to a mirror table. +MODULE_CACHE_DATABASES = { + "customer_data": {"label": "Odoo customers", "cache_prefix": "pool"}, + "product_data": {"label": "Odoo products", "cache_prefix": "product_pool"}, +} +# The Assistant predates the public taxonomy above. Its private name remains an alias so its +# snapshot-only contract and every existing caller stay byte-for-byte unchanged. +_ASSISTANT_BUILT_INS = MODULE_CACHE_DATABASES + + +def module_cache_source(database: str): + """Metadata for a runtime-cache database, or None for every materialised/mirror key.""" + meta = MODULE_CACHE_DATABASES.get(str(database or "")) + return dict(meta) if meta else None + + +def module_cache_rows(session: Session, database: str): + """The current viewer's scoped rows for one known runtime-cache database. + + This is deliberately the interactive grid boundary, not the Assistant snapshot reader: + `scoped_table` applies the same team/agent and row grants as the module page, while + `Session.require` keeps the account and tenant-catalogue checks in their one chokepoint. + Unknown keys fail before either check, so an absent relation target cannot be mislabeled as + a permission denial. + """ + key = str(database or "") + if module_cache_source(key) is None: + raise KeyError(key) + session.require(key) + import core.perm_scope as perm_scope + return list(perm_scope.scoped_table(session.user, key, st=session.runtime) or []) + + +def _assistant_refuse(status, code, message): + """Raise the public error shape without exposing a source implementation detail.""" + raise err(status, code, message) + + +def _assistant_tenant_allows(session: Session, database: str) -> bool: + """Read the served tenant catalogue without reusing the legacy account gate.""" + tenant = getattr(getattr(session, "runtime", None), "tenant", None) + config = getattr(tenant, "config", None) or {} + modules = config.get("modules", "all") if isinstance(config, dict) else "all" + return modules == "all" or str(database) in {str(key) for key in (modules or ())} + + +def _assistant_preflight_request(session: Session, database: str, canonical_fields, + requested_fields, filters, *, require_explicit_grant: bool): + """Refuse an unresolved grant, field or filter before a stored record is touched.""" + import core.perm_scope as perm_scope + + grant = perm_scope.assistant_entry(session.user, database) + if require_explicit_grant and grant is None: + _assistant_refuse(403, "assistant_forbidden", + "your current permissions do not allow this database") + visible = (perm_scope.assistant_visible_fields(canonical_fields, session.user, database) + if grant is not None else list(canonical_fields or ())) + try: + perm_scope.validate_assistant_filter((grant or {}).get("filter"), canonical_fields) + _assistant_requested_fields(requested_fields, visible) + perm_scope.validate_assistant_filter(filters, visible) + except ValueError as exc: + _assistant_refuse(400, "assistant_bad_filter", str(exc)) + return grant, visible + + +def _assistant_cached_builtin(session: Session, database: str, requested_fields=None, filters=None): + """The exact in-process snapshot for one built-in database, or a loud cache-miss refusal. + + This intentionally reads `runtime.pool_cache` directly. Calling either route's `_pool_for` + would make a first Assistant request call Odoo; calling a cache helper would make a stale entry + refresh. Neither is data already stored/served by this process. + """ + import core.perm_scope as perm_scope + + # Unlike an interactive grid, the Assistant has no legacy-grant compatibility path: the + # caller needs a declared, migrated database grant. `may_access` retains the old wall for + # the grid rollout, so it is necessary but not sufficient at this boundary. + declared_access = perm_scope.assistant_entry(session.user, database) is not None + if not _assistant_tenant_allows(session, database) or not declared_access: + _assistant_refuse(403, "assistant_forbidden", + "your current permissions do not allow this database") + + # These are static field contracts, not the route assemblies: route assemblies can add + # per-user workspace state and can call a source builder. The Assistant begins with the + # already-stored base rows only; resolve their grant/field/filter contract *before* the cache + # read so a denied field or malformed operand cannot touch a stored record. + import aios_grid + fields = aios_grid.FIELDS if database == "customer_data" else aios_grid.product_fields() + _assistant_preflight_request(session, database, fields, requested_fields, filters, + require_explicit_grant=True) + + team_id, agent = perm_scope.derive_pool_scope(session.user, database) + cache_key = (("pool", team_id, agent) if database == "customer_data" + else ("product_pool", team_id)) + cache = getattr(session.runtime, "pool_cache", None) + entry = cache.get(cache_key) if isinstance(cache, dict) else None + if (not isinstance(entry, tuple) or len(entry) < 2 + or not isinstance(entry[1], (list, tuple)) + or any(not isinstance(row, dict) for row in entry[1])): + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database has no app-stored snapshot for your current scope") + return list(entry[1]), [dict(field) for field in fields if isinstance(field, dict)], entry[0] + + +#: ⭐⭐ THE TWO WAYS A `ut_*` DATABASE REACHES THE ASSISTANT, AS A SET RATHER THAN AN `or`. +#: Both are walled by `user_tables.may_open` inside their reader, which is why both tolerate a +#: `None` assistant grant at the row/field projection below - and why a THIRD user-table source +#: added later must be added here too or it will be refused for the wrong reason. +_ASSISTANT_USER_TABLE_KINDS = frozenset({"materialised_user_table", "mirror_user_table"}) + + +def _assistant_table_defn(session: Session, database: str): + """The rows-free definition for one `ut_*` database plus its lent runtime, after `may_open`. + + ⛔ THE ROWS-FREE PROJECTION IS THE POINT, not a micro-optimisation. A guessed `ut_*` key must + never make `user_tables.get()` copy the tenant's rows before the table resolver refuses it, + and `all_defs` can fall back to a whole-document read for older stores, so the runtime's + projection primitive is used directly and an absent one fails closed. The existing `may_open` + remains THE resolver; it is lent this rows-dropped document. + + ⭐ FACTORED OUT (W47-T23) because there are now TWO readers behind this one wall - the + materialised document reader and the mirror reader - and `assistant_read_scope` has to know + which of them applies BEFORE it calls either. Reading the projection once and handing the + definition down keeps that dispatch from costing a second store read, and keeps the two + readers from growing two ideas of who may open a database. + """ + from core import user_tables + + try: + definitions = session.runtime.get_projection('user_tables', drop=('rows',)) + except Exception: + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database has no readable definition snapshot") + if not isinstance(definitions, dict): + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database has no readable definition snapshot") + definition = definitions.get(database) + if not isinstance(definition, dict): + _assistant_refuse(404, "assistant_unknown_database", "that database is not available") + definition_runtime = user_tables.lend(session.runtime, user_tables=definitions) + if not user_tables.may_open(database, session.uname, session.admin, st=definition_runtime): + # Deliberately no label/owner in this response: knowing a key must not become an oracle + # for somebody else's database. + _assistant_refuse(403, "assistant_forbidden", + "your current permissions do not allow this database") + return definition, definition_runtime + + +def _assistant_user_table(session: Session, database: str, requested_fields=None, filters=None, + *, defn=None, lent=None): + """Read a materialised user-table document after a rows-free database grant check.""" + from core import user_tables + + definition, _lent = ((defn, lent) if isinstance(defn, dict) + else _assistant_table_defn(session, database)) + + fields = [dict(field) for field in (definition.get("fields") or []) + if isinstance(field, dict) and field.get("key")] + _assistant_preflight_request(session, database, fields, requested_fields, filters, + require_explicit_grant=False) + + # Only an admitted table may now cross the app-stored record seam. This call still has no + # upstream fallback: it is the tenant's materialised document already held by the runtime. + table = user_tables.get(database, st=session.runtime) + if not isinstance(table, dict): + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database changed before its stored snapshot could be read") + if not user_tables.materialises(database, st=session.runtime, defn=table): + # ⭐⭐ W47-T23 / R11 - THIS IS NO LONGER THE ANSWER FOR A MIRROR-SERVED DATABASE, and the + # seam this comment used to ask for now exists: `assistant_mirror.py`, reached through + # `_assistant_mirror_table`. `assistant_read_scope` reads `materialises` off the rows-free + # DEFINITION and dispatches there before this reader is ever entered. + # ⚠ SO WHAT SURVIVES HERE IS A RACE GUARD, NOT A POLICY. It fires only when the definition + # said "materialised" at dispatch and the fetched document says otherwise, i.e. the table + # was un-materialised between the two reads. Returning an empty table would be a false + # answer, so it still refuses; it is simply no longer the ten `ut_odoo_*` grids' fate. + # ⛔ DO NOT "FIX" THIS BY FLIPPING `readThrough`. D-378 says these tables' classification + # is separately wrong; changing the flag to make a read pass would hide that defect and + # move ten grids onto the wrong reader. + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database stopped storing its rows while it was being read; ask " + "again and it will be read from its connector mirror instead") + + # A table's field contract was authorized from the rows-free definition. If it changed while + # the materialised document was fetched, fail rather than projecting a schema that was never + # checked. + actual_fields = [dict(field) for field in (table.get("fields") or []) + if isinstance(field, dict) and field.get("key")] + if actual_fields != fields: + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database changed before its stored snapshot could be read") + raw_rows = table.get("rows") or {} + if not isinstance(raw_rows, dict): + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database does not have a readable stored snapshot") + keys = {field["key"] for field in fields} + rows = [] + for record_id, raw in raw_rows.items(): + if not str(record_id).isdigit() or not isinstance(raw, dict): + continue + # Matches `routes_tables.scoped_pool`: user-table permission is table-level, and only + # declared fields cross this boundary. `pid` is the opaque record identity required to + # bind a returned record to a single-source Query artefact; it is not a selectable field. + rows.append({"pid": int(record_id), + **{key: raw.get(key) for key in keys if key in raw}}) + rows.sort(key=lambda row: row["pid"]) + return rows, fields, (table.get("updated") or table.get("created")), table.get("label") or database + + +def _assistant_mirror_table(session: Session, database: str, requested_fields=None, filters=None, + *, defn=None, lent=None): + """Read a MIRROR-SERVED user table through the same filter compiler the grid uses (R11 / C7). + + Returns `_assistant_user_table`'s 4-tuple - `(rows, fields, source_version, label)` - so the + dispatcher below can swap one for the other and nothing downstream changes. + + ⭐⭐ OWNER R11, VERBATIM: *"Why can't it be queried by the AI if user has access to it? just + query it using our own Filter work. I want the AI to be able to use our tools."* Ten + `ut_odoo_*` databases were offered to the assistant and refused one spent prompt at a time, + because their rows left the tenant document for the DuckDB mirror and this boundary had no + mirror reader. It has one now, and it is the grid's own: `routes_odoo_tables`'s cursor guard, + its column resolver, its window, and `harness.filter_sql`. + + ⛔ THE OPENING IS `_assistant_user_table`'S, DELIBERATELY UNCHANGED - rows-free projection, + `may_open`, `_assistant_preflight_request`. C7: *"the assistant's existing permission + validation"*, reused rather than restated. Only the ROW SOURCE differs. + ⛔ AND IT NEVER CALLS `user_tables.get()`. That whole-document read is precisely what this + path exists to avoid: the rows are not in the document, and fetching 28.6 MB to discover that + is the cost `assistant_permitted_sources` was written to stop paying. + + ⚠ THE FIELD CONTRACT IS `mk_fields()` INTERSECTED WITH THE MIRROR'S COLUMNS, not the stored + `fields`. A declared field with no mirror expression (a link, a rollup) cannot be answered + from SQL, so offering it would return it silently absent; left out, `_assistant_requested_fields` + refuses a request naming it with a loud `assistant_unknown_field`. The preflight therefore + runs against THAT list, so the grant, the wall and the request are all validated against what + can actually be read. + """ + import assistant_mirror + import core.perm_scope as perm_scope + + definition, _lent = ((defn, lent) if isinstance(defn, dict) + else _assistant_table_defn(session, database)) + + # THE CHEAP QUESTION FIRST, and it needs no cursor: is this key a connected Odoo grid at all? + # A `readThrough` table that is not one has no mirror rows anywhere, and asking the mirror + # about it would open a cursor to learn nothing. + if assistant_mirror.declared_fields(database) is None: + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database does not store its rows and it is not one of the " + "connected databases the assistant can read from the mirror") + cur, refusal = assistant_mirror.open_cursor(session) + if refusal is not None: + _assistant_refuse(refusal.status, refusal.code, refusal.message) + spec = assistant_mirror.binding(cur, database) + if spec is None: + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database is served live from its connector and this deployment " + "has no read-through binding for it yet, so it holds no rows to read") + fields = assistant_mirror.answerable_fields(database, spec) + if not fields: + _assistant_refuse(409, "assistant_snapshot_unavailable", + "this database's connector mirror carries none of its declared columns " + "on this deployment, so there is nothing to answer from") + + grant, visible = _assistant_preflight_request(session, database, fields, requested_fields, + filters, require_explicit_grant=False) + + # ⛔ COMPILE THE **VALIDATED** TREES, NEVER THE RAW ONES, and this is what makes the done-when + # structural rather than lucky. `assistant_read_scope` runs `filter_eval.permits` over + # `validate_assistant_filter`'s RETURN, and `assistant_apply_row_scope` over the grant's tree. + # Pushing the raw input to SQL instead would mean the pushdown and the Python pass are two + # predicates that happen to agree, which is this repo's recorded defect class. Same input to + # both compilers, same answer by construction. + try: + wall_tree = perm_scope.validate_assistant_filter((grant or {}).get("filter"), fields) + filter_tree = perm_scope.validate_assistant_filter(filters, visible) + except ValueError as exc: + _assistant_refuse(400, "assistant_bad_filter", str(exc)) + raise # unreachable; keeps the names bound for a reader + # ⚠ NO GRANT MEANS NO ROW WALL ON THIS PATH, matching `assistant_read_scope` exactly: it + # applies `assistant_apply_row_scope` only when a grant resolved, because `may_open` above is + # what admitted a user table. Pushing a wall down that Python will not apply would narrow the + # answer below what the caller is entitled to, which is a wrong number in the other direction. + if grant is None: + wall_tree = None + + try: + rows, stamp, total = assistant_mirror.read_rows( + session, database, cur, spec, fields, + wall_tree=wall_tree, filter_tree=filter_tree, + filter_keys=[field["key"] for field in visible + if isinstance(field, dict) and field.get("key")]) + except assistant_mirror.MirrorRefusal as exc: + _assistant_refuse(exc.status, exc.code, exc.message) + raise # unreachable; see above + + # ⭐ PROVENANCE A CITATION CAN CARRY. `routes_query._system_prompt` runs + # `json.dumps(source_version, default=str)`, so this stays plain JSON: when the mirror last + # reconciled this table against its connector, and how many rows the answer was computed over. + # The count is here because the model is told the record count separately, and a reader + # checking one against the other should find the same integer. + source_version = {"read": "connector mirror", "refreshed": stamp, "rows": total} + return rows, fields, source_version, definition.get("label") or database + + +def _assistant_requested_fields(fields, visible_fields): + """Resolve an explicit field selection without turning an unknown key into an omission.""" + by_key = {str(field.get("key")): field for field in visible_fields + if isinstance(field, dict) and field.get("key")} + if fields is None: + return list(by_key) + if not isinstance(fields, (list, tuple)): + _assistant_refuse(400, "assistant_bad_fields", "fields must be a list of field keys") + out = [] + for raw in fields: + key = raw.strip() if isinstance(raw, str) else "" + if not key or key not in by_key or key in out: + _assistant_refuse(400, "assistant_unknown_field", + "every requested field must be visible in this database") + out.append(key) + return out + + +def assistant_read_scope(session: Session, database, fields=None, filters=None): + """Return a detached, permissioned snapshot for one Assistant tool call. + + Signature (the C8 contract for E): + assistant_read_scope(session, database, fields, filters) -> { + database, label, source_kind, source_version, retrieved_at, + permission_scope_applied, fields, filters, records + } + + `database` is exactly one source. `fields` is an explicit list of visible field keys (or + ``None`` for every visible field). `filters` is ``None`` or the strict tree accepted by + `core.perm_scope.validate_assistant_filter`; it rejects unknown, hidden, inactive and + unsupported operands before a row is read. The returned dictionaries are deep copies, never + a live cache/store object, cursor, connector, route, provider, or credential. + """ + import core.perm_scope as perm_scope + from harness import filter_eval + + key = str(database or "").strip() + if key in _ASSISTANT_BUILT_INS: + rows, canonical_fields, source_version = _assistant_cached_builtin(session, key, fields, filters) + label = _ASSISTANT_BUILT_INS[key]["label"] + source_kind = "runtime_cache" + elif key.startswith("ut_"): + # ⭐⭐ W47-T23 / R11 - TWO READERS BEHIND ONE WALL, CHOSEN OFF THE ROWS-FREE DEFINITION. + # `_assistant_table_defn` is read ONCE here and lent to whichever reader applies, so the + # dispatch costs no extra store read and the two readers cannot grow two ideas of who may + # open a database. `materialises` is the FIRST of the two predicates + # `assistant_source_status` reports `answerable` from, and the mirror binding is the + # second, so the picker and the reader admit the same set by construction. + # ⛔ THE FLAG IS READ, NEVER WRITTEN. D-378 says these tables' `readThrough` classification + # is separately wrong; the fix for that is not to reclassify them here so a read passes. + from core import user_tables + _defn, _lent = _assistant_table_defn(session, key) + if user_tables.materialises(key, st=_lent, defn=_defn): + rows, canonical_fields, source_version, label = _assistant_user_table( + session, key, fields, filters, defn=_defn, lent=_lent) + source_kind = "materialised_user_table" + else: + rows, canonical_fields, source_version, label = _assistant_mirror_table( + session, key, fields, filters, defn=_defn, lent=_lent) + source_kind = "mirror_user_table" + else: + _assistant_refuse(404, "assistant_unknown_database", "that database is not available") + + # Permanent permissions run against the full source contract. A permission filter may name + # a field that is intentionally hidden from the returned schema; resolving it after the field + # projection would make that filter unanswerable and (depending on the evaluator) could widen. + # Validate even that grant before evaluating it: `permits` would deny an unknown operand row + # by row, but the Assistant contract requires an explicit refusal for unresolved grants. + grant = perm_scope.assistant_entry(session.user, key) + if source_kind not in _ASSISTANT_USER_TABLE_KINDS and grant is None: + # `_assistant_cached_builtin` already made this decision before touching its cache. Keep + # this guard adjacent to the field/row projection so a future source cannot forget it. + # ⚠ A SET, NOT AN `or`, AND BOTH USER-TABLE KINDS ARE IN IT (W47-T23). Either reader has + # already passed `user_tables.may_open`, which is the wall for that family; requiring a + # SECOND, assistant-specific grant here would refuse a table the user demonstrably holds. + # Spelled as membership so a third user-table source is one line, not a growing chain. + _assistant_refuse(403, "assistant_forbidden", + "your current permissions do not allow this database") + try: + perm_scope.validate_assistant_filter((grant or {}).get("filter"), canonical_fields) + except ValueError as exc: + _assistant_refuse(400, "assistant_bad_filter", str(exc)) + # ⭐ OWNER I16 — the tenant handle rides into the row wall here too, so one stored rule means + # the same thing in the Analyst's answer as it does on the grid (see + # `perm_scope._enrich_for_wall`). + # + # ⚠ AND IT CHANGES NOTHING ON THIS PATH TODAY, WHICH IS STATED RATHER THAN LEFT TO BE + # REDISCOVERED. `validate_assistant_filter` three lines up refuses any leaf naming a column + # outside `canonical_fields`, so a wall on a user-generated column is rejected before it can + # reach this call at all. The handle is passed anyway because the alternative is a door that + # walls these modules WITHOUT it — and "all six or none" is the property that keeps one wall + # from having two meanings. Widening the Assistant's own validator to admit such a column is + # a separate decision about what E may read, not a side effect of a grid fix. + permitted_rows = (perm_scope.assistant_apply_row_scope(rows, session.user, key, + canonical_fields, + st=getattr(session, "runtime", None)) + if grant is not None else list(rows or ())) + visible = (perm_scope.assistant_visible_fields(canonical_fields, session.user, key) + if grant is not None else list(canonical_fields)) + selected_keys = _assistant_requested_fields(fields, visible) + try: + requested_filter = perm_scope.validate_assistant_filter(filters, visible) + except ValueError as exc: + _assistant_refuse(400, "assistant_bad_filter", str(exc)) + if requested_filter is not None: + permitted_rows = [row for row in permitted_rows + if filter_eval.permits(requested_filter, row, visible)] + + records = [] + for row in permitted_rows: + if not isinstance(row, dict) or row.get("pid") is None: + continue + records.append({"pid": copy.deepcopy(row["pid"]), + **{field: copy.deepcopy(row.get(field)) for field in selected_keys}}) + + return { + "database": key, + "label": str(label), + "source_kind": source_kind, + "source_version": copy.deepcopy(source_version), + "retrieved_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), + "permission_scope_applied": True, + "fields": [copy.deepcopy(field) for field in visible + if field.get("key") in selected_keys], + "filters": copy.deepcopy(requested_filter), + "records": records, + } + + +def assistant_permitted_sources(session: Session, databases): + """Which of `databases` the caller may still read — WITHOUT reading one record. + + ⛔ THIS EXISTS BECAUSE `GET /query` LISTS ARTEFACTS, AND AN ARTEFACT IS NOT A READ. + `routes_query._public_state` has to drop every saved view whose source the caller has since + lost. The obvious way to ask that question is `assistant_read_scope(..., fields=[])` — and it + is the wrong one: for a `ut_*` source that call runs `user_tables.get()`, i.e. a WHOLE-DOCUMENT + read of the tenant store (measured at **28.6 MB / 703 ms warm on tenant #0**, and 99.9% of those + bytes are `rows` this question does not look at), then projects every row down to its `pid` and + throws the result away. Once per saved view, up to `MAX_ARTIFACTS = 200` of them, on a route + that BOTH the Assistant and Query call on mount. That is `/nav`'s old 1+N whole-document read + (D-175, an 11.0 s median) rebuilt inside a new route, and every fixture with two artefacts + passes it [[measure-the-real-call]]. + + So this asks the permission question and ONLY the permission question: + * the rows-free `user_tables` projection is read at most ONCE for the whole batch, and lent + to `may_open` exactly as `_assistant_user_table` lends it; + * a built-in resolves from the tenant catalogue and the declared grant, with no `pool_cache` + read — a cache MISS is a data-availability fact, not a permission one, and refusing to list + an artefact because its snapshot is cold would silently delete the user's history from the + rail every time the process restarted [[empty-answer-vs-unfinished-answer]]. + + ⚠ It is deliberately NOT a second permission wall. Every predicate here is the same call + `assistant_read_scope` makes for the same source; nothing may be admitted here that the read + boundary would refuse, which is what `verify_query.py` asserts in both directions. + """ + return {key for key, row in assistant_source_status(session, databases).items() + if row["permitted"]} + + +def assistant_source_status(session: Session, databases=None): + """`{key: {permitted, answerable, reason}}` — WITHOUT reading one record. + + ⭐⭐ `answerable` EXISTS BECAUSE `permitted` IS NOT THE QUESTION THE READER IS ASKING. + Measured on tenant #0, signed in, 2026-08-15: the Assistant offered **twelve** source chips + and could answer for **two**. The other ten are the `ut_odoo_*` grids, and + `_assistant_user_table` refused every one of them because their rows live UNCAPPED in the + DuckDB mirror and are read through it (W30/R6 is exactly why). The refusal was correct, named + and fail-closed. The defect was that it arrived one spent prompt at a time: a picker that + offers ten doors which cannot open is the same shape as the rail that painted two rows + differently from five. + ⚠ It is R6's SECOND SENTENCE, in the family that rule was written for — a limit that cannot be + removed must be REPORTED with its cause, never silently enforced. + + ⭐⭐ W47-T23 / OWNER R11 — **THE LIMIT IS NOW CLOSED, NOT EXPLAINED**, so `answerable` has TWO + ways to be true. Owner: *"Why can't it be queried by the AI if user has access to it? just + query it using our own Filter work. I want the AI to be able to use our tools."* A `ut_*` + database is answerable when it materialises OR when this deployment has a read-through + binding for it, because `_assistant_mirror_table` reads that binding through the same filter + compiler the grid uses. MEASURED on this worktree, all eight connected grids declared + read-through: **four answerable** (`ut_odoo_accounts`, `ut_odoo_gl_lines`, + `ut_odoo_order_lines`, `ut_odoo_orders`), four still reported with their cause, which is that + this deployment's mirror carries no table behind them. + + ⛔ IT NO LONGER COSTS NOTHING, AND THE PRICE IS STATED RATHER THAN LEFT TO BE FOUND. + `user_tables.materialises()` reads the `readThrough` flag off the DEFINITION the rows-free + projection already carries, so the first predicate is still free. The second needs the mirror. + MEASURED warm, median of five, whole batch of ten sources on this worktree: **0.5 ms before, + 15.6 ms after (+15.1 ms)**, using ONE cursor for the batch and `assistant_mirror.is_bound` + rather than a full spec resolve. The full resolve was tried FIRST and measured **+605 ms**, + because `_source_for` runs `excluded_ids`, a scan of every partner row, once per grid; + `is_bound`'s docstring carries that measurement and the reason it is safe to stop short of it. + + ⚠ `databases=None` enumerates every source this tenant HAS (the two built-ins plus every + `ut_*` in the projection) rather than taking a caller-supplied list. A client list would make + the answer depend on what the caller thought to ask about, and the nav has already told them + what they hold. + """ + import core.perm_scope as perm_scope + from core import user_tables + + definitions = None + read_definitions = False + mirror_cur = None + read_mirror = False + + def _mirror(): + """The batch's ONE mirror cursor, opened lazily, or None. Never raises. + + ⭐⭐ W47-T23 - `answerable` NOW HAS A SECOND WAY TO BE TRUE, because the assistant can + read a mirror-served database (R11). A table that does not materialise is answerable when + this deployment has a read-through binding for it, so this batch has to ask the mirror. + ⛔ AT MOST ONE CURSOR, AND ONLY WHEN SOMETHING NEEDS IT. `databases=None` enumerates every + source the tenant has, and this function is called on mount by both the Assistant and + Query; a cursor per key, or a cursor on a tenant with no read-through tables at all, would + put a mirror open on the hot path of a route that used to touch one projection. Opened on + first need, reused for the rest of the batch, closed by the process as before. + ⚠ FAIL-QUIET TO `None`, unlike the READ path. This function reports availability; if the + mirror cannot be opened, the honest answer is "not answerable yet, and here is why", + which is the branch below. A raise here would take down the whole picker over one source. + """ + nonlocal mirror_cur, read_mirror + if not read_mirror: + read_mirror = True + try: + import assistant_mirror + cur, refusal = assistant_mirror.open_cursor(session) + mirror_cur = None if refusal is not None else cur + except Exception: # noqa: BLE001 + mirror_cur = None + return mirror_cur + + def _definitions(): + nonlocal definitions, read_definitions + if not read_definitions: + read_definitions = True + try: + candidate = session.runtime.get_projection('user_tables', drop=('rows',)) + except Exception: + candidate = None + definitions = candidate if isinstance(candidate, dict) else None + return definitions + + if databases is None: + wanted = list(_ASSISTANT_BUILT_INS) + [ + key for key in sorted((_definitions() or {})) + if isinstance(key, str) and key.startswith("ut_") + ] + else: + wanted = [str(key or "").strip() for key in (databases or ())] + wanted = list(dict.fromkeys(key for key in wanted if key)) + + out = {} + for key in wanted: + # `visible` = "the caller can open this database elsewhere in the product". D-276 uses it + # to decide whether an unusable source is REPORTED or stays absent; default False, so a + # branch that never sets it keeps today's silence rather than inheriting a disclosure. + row = {"permitted": False, "answerable": False, "reason": "", "visible": False} + out[key] = row + if key in _ASSISTANT_BUILT_INS: + # ⭐⭐ D-276 (2026-08-15) — AN OMISSION MUST STATE ITS CAUSE, and this branch used to + # `continue` in silence. MEASURED on tenant #0, both `admin` and `leadership`: + # `GET /query` listed nine sources and `product_data` was not among them, while + # `POST /query/chat {database:"product_data"}` answered 403 `assistant_forbidden` — + # for a database the SAME account opens from the nav, holds saved views on, and can + # see in the Database flyout. The mirror-served grids were un-askable too and they + # WERE listed, with their cause in the chip; this one said nothing at all. (W47-T23 + # has since made those grids readable, so the contrast is now with the four whose + # mirror table this deployment does not carry; the asymmetry this branch fixes is + # unchanged.) + # ⛔ THE ASYMMETRY IS THE DEFECT, NOT THE REFUSAL. R6's second sentence: a limit that + # cannot be removed must be REPORTED with its cause, never silently enforced. + # ⚠ `visible` IS WHAT KEEPS THIS FROM BEING A DISCLOSURE. A source the caller cannot + # open ANYWHERE stays absent — naming it would tell them a database exists that they + # were never allowed to know about. `visible` is true only when the ordinary product + # wall already lets them open it, i.e. when the silence was incoherent rather than + # protective. `permitted` is untouched: it gates which stored artefacts survive, and + # widening it here would resurrect views the read boundary refuses. + if not _assistant_tenant_allows(session, key): + row["visible"] = bool(perm_scope.may_access(session.user, key)) + row["reason"] = ("this workspace's catalogue does not list it as an assistant " + "source. An administrator can add it") + continue + if perm_scope.assistant_entry(session.user, key) is None: + row["visible"] = bool(perm_scope.may_access(session.user, key)) + # ⛔⛔ THIS SENTENCE DELIBERATELY PROMISES NO REMEDY, AND THAT IS A CORRECTION. + # Its first version said *"an administrator can re-save them"*. MEASURED on the + # deployed build the same hour: re-saving `leadership`'s permissions through + # `PUT /admin/users/{u}/perms` returned 200 with the block byte-identical and + # `perms_v` unchanged at 1 — and the source stayed refused. So the advice was + # wrong, and a refusal that hands the reader a fix which does not work is worse + # than one that admits it does not know: they spend the trip and land back here. + # ⚠ The cause is still open (D-276). `assistant_entry` reads only `entry`, + # `is_migrated` and `may_access`, and `product_data` carries the SAME grant as + # `customer_data` under one record — so the divergence is not visible in the perms + # document and guessing at it once already produced a wrong answer. + row["reason"] = ("the assistant cannot resolve a data grant for it yet. This is a " + "known gap (D-276), not something you have set wrongly") + continue + row["permitted"] = True + # ⚠ A CACHE MISS IS A DATA-AVAILABILITY FACT, NOT A PERMISSION ONE, and it must not + # drop the source from the list — an artefact already built on it stays listed. It is + # reported as not-yet-answerable, with the action that fixes it. MEASURED: the pool is + # filled by a grid REQUEST, not by `AIOS_PREWARM` — a fresh process refuses until + # somebody opens the database once. + team_id, agent = perm_scope.derive_pool_scope(session.user, key) + cache_key = (("pool", team_id, agent) if key == "customer_data" + else ("product_pool", team_id)) + cache = getattr(session.runtime, "pool_cache", None) + entry = cache.get(cache_key) if isinstance(cache, dict) else None + if isinstance(entry, tuple) and len(entry) >= 2 and isinstance(entry[1], (list, tuple)): + row["answerable"] = True + else: + row["reason"] = "no snapshot loaded yet. Open this database once, then ask" + continue + if not key.startswith("ut_"): + continue + defs = _definitions() + definition = (defs or {}).get(key) + if not isinstance(definition, dict): + continue + lent = user_tables.lend(session.runtime, user_tables=defs) + if not user_tables.may_open(key, session.uname, session.admin, st=lent): + continue + row["permitted"] = True + if user_tables.materialises(key, st=lent, defn=definition): + row["answerable"] = True + continue + # ⭐⭐ W47-T23 / R11 - THE SECOND WAY TO BE ANSWERABLE. This used to end here with a flat + # "the assistant cannot read it yet", which was true of every mirror-served grid and is + # now true of none that this deployment binds. `_assistant_mirror_table` reads them + # through the same filter compiler the grid uses, so the picker must stop saying they are + # shut. + # ⛔ THE REASON STILL HAS TO NAME ITS CAUSE (R6's second sentence), and the two remaining + # causes are DIFFERENT causes with different fixes: a mirror that cannot be opened at all + # is transient and retrying works, while a grid this deployment has no read-through + # binding for will not fix itself by waiting. One sentence for both would make the first + # look permanent, which is the failure mode the ruling exists to prevent. + cur = _mirror() + if cur is None: + row["reason"] = ("this database is read live from its connector mirror, and that " + "mirror is not open on this deployment right now; try again shortly") + continue + # ⛔ `is_bound`, NOT `binding` - THE AVAILABILITY QUESTION, NOT THE READ ONE, and the + # difference is 300 ms PER KEY here. Resolving a full spec runs `excluded_ids`, a scan of + # every partner row, for three of this tenant's grids; measured, it put +605 ms on this + # batch, which is called on mount by both the Assistant and Query. See `is_bound`. + try: + import assistant_mirror + bound = assistant_mirror.is_bound(cur, key) + except Exception: # noqa: BLE001 + bound = False + if bound: + row["answerable"] = True + else: + row["reason"] = ("this database is read live from its connector mirror, and this " + "deployment has no read-through binding for it yet, so it holds no " + "rows the assistant can read") + return out + + +def _user_for(claims): + """The account named by a verified cookie, or None — with the epoch check that makes a + stateless cookie revocable. + + ⛔ THE RULE THIS FUNCTION MUST OBEY: **it has to accept exactly the identities the login route + issues.** Any divergence produces the worst failure shape there is — a login that returns 200 + with a cookie and then 401s every request after it. + + TWO CASES: + * THE RECORD, if it is readable and satisfies everything a session adds on top of a login: + the account is active, and its CURRENT epoch equals the cookie's — otherwise the session + is revoked (a password change or a deactivation bumped it). + * THE QA RUNNER, only when both non-production deployment gates remain enabled and its + password-derived epoch still matches. Live deployments cannot enable it. + * anything else → None. An unknown username is NOT admitted just because its signature was + valid: a signature proves the cookie is ours, not that the account still exists. + """ + uname = (claims.get("u") or "").strip().lower() + if not uname: + return None + claim_tenant = str(claims.get("t") or "").strip().lower() + # W39-T28 / A62. This MUST precede the registry read: qa-runner is specifically a + # zero-touch qa-b identity, not an account in tenant #0's `users` document. The helper + # rechecks both non-production deployment flags, so removing either invalidates its cookie. + qa = users.qa_identity(uname) + if (qa and claim_tenant == qa.get("tenant") + and int(claims.get("e") or 0) == int(qa.get("epoch") or 0)): + return qa + try: + reg = users.registry() or {} + except Exception: + reg = {} + rec = reg.get(uname) + if (rec and rec.get("active", True) + and int(rec.get("epoch") or 0) == int(claims.get("e") or 0)): + pub = users._public(uname, rec) + # ⛔ Wave 18 (C1-TENANT, R1): the cookie's tenant must be THE ACCOUNT'S tenant. Before + # this line, any valid credential could mint a session for any registered slug + # (login validated the slug's existence, never the membership) — with + # AIOS_ENABLE_QA_TENANT=1 that was a working cross-tenant session. A signature proves + # the cookie is ours; THIS proves the account belongs where the cookie says it does. + # ⚠ WAVE 33 (W33-T37) — the default was DELETED, not changed. It read + # `pub.get("tenant", "royal-imports")` and could never fire: `users._public` normalises a + # missing tenant to `royal-imports` before this line ever sees it. A dead default that + # names a real tenant reads like a live fallback, and the cross-tenant audit spent a row + # proving it was not one. Bare `.get` is also the safer shape if that ever stops being + # true: `None != claim_tenant` denies, where the old default would have ADMITTED a + # tenant-less record into tenant #0's session. + if claim_tenant != pub.get("tenant"): + return None + return pub + return None + + +# --- wave 19 (R4): the LAST-ACTIVE stamp, throttled in this process ------------------------------ +# "Is anyone actually using this account?" is one of the two questions the Loopable admin plane +# answers, and the only place that can honestly answer it is the session resolver — every +# authenticated request passes through here. +# +# ⛔ THEREFORE IT MUST COST ALMOST NOTHING. A store write per request would put the HF store's +# 256-commits/hour budget on the critical path of the entire API, and a store READ per request to +# decide whether to write would be little better. So the staleness decision is made from a +# PROCESS-LOCAL map: no I/O at all on the 99.97% of requests inside the window, and the write +# itself (once an hour per account) happens on `core.users`' own background thread, so no request +# ever waits for a hub round-trip. `core.users` explains why that write is SYNC and not the +# coalesced async path — `users.json` is shared with the Streamlit host and an async flush rebases +# on this process's cache, which would let a stamp revert somebody else's deactivation. +# +# HONEST LIMITS, stated rather than discovered later: the map is per-process, so N workers can each +# write once per window (still bounded); a restart re-arms every user's first request; and the +# resolution of `last_active` is therefore "within the last hour", which is exactly what the plane +# renders it as. Bounded independently so it cannot grow into a leak on a deployment +# with many accounts. +_ACTIVE_SEEN: "OrderedDict[str, float]" = OrderedDict() +_ACTIVE_EVERY = float(os.environ.get("AIOS_ACTIVE_STAMP_SECONDS") or 3600) +_ACTIVE_MAX_TRACKED = 4096 + +#: ⚠ MUST MATCH `web/src/apiContract.ts::TENANT_HEADER` EXACTLY — the client compares this +#: header against the tenant its frame booted with, and a rename on one side alone turns the +#: guard OFF silently (an absent header reads as "no change", by design, so nothing would go +#: red). `verify_wiring.py` pins both spellings for that reason. +_TENANT_HEADER = "X-AIOS-Tenant" + + +def note_active(uname, when=None): + """Record that `uname` was just seen — WITHOUT writing. The login path calls this because it + has already stamped `last_active` itself; without it the very next request would find no entry + and stamp again immediately, making the "at most once an hour" rule false by one write per + sign-in.""" + key = (uname or "").strip().lower() + if not key: + return + _ACTIVE_SEEN[key] = when if when is not None else time.time() + _ACTIVE_SEEN.move_to_end(key) + while len(_ACTIVE_SEEN) > _ACTIVE_MAX_TRACKED: + _ACTIVE_SEEN.popitem(last=False) + + +def _touch_active(uname): + """Stamp `last_active` at most once per window per account, per process. Never raises.""" + try: + key = (uname or "").strip().lower() + if not key: + return + now = time.time() + last = _ACTIVE_SEEN.get(key) + if last is not None and (now - last) < _ACTIVE_EVERY: + return + note_active(key, now) + users.touch_active(key) + except Exception: # noqa: BLE001 — telemetry may never break a request + pass + + +def require_session(request: Request, response: Response) -> Session: + """Verify the cookie, resolve the tenant, and REISSUE the cookie (the 8h idle window is + refreshed on use; the 30-day absolute expiry is carried over, never extended).""" + raw = request.cookies.get(aios_session.COOKIE_NAME) + if not raw: + raise err(401, "no_session", "sign in to continue") + claims = aios_session.read(raw) + if not claims: + raise err(401, "invalid_session", "your session has expired. Sign in again") + user = _user_for(claims) + if not user: + raise err(401, "invalid_session", "your session has expired. Sign in again") + try: + rt = runtime.get_runtime(claims["t"]) + except KeyError: + # An unknown tenant slug is a 401, not a 404: the cookie is not a valid identity for this + # deployment, and confirming which slugs exist would answer a question we were not asked. + raise err(401, "invalid_session", "your session has expired. Sign in again") + fresh, _ = aios_session.mint(claims["t"], user["username"], int(user.get("epoch") or 0), + absolute_expiry=claims["x"]) + aios_session.set_cookie(response, request, fresh) + # ⭐ STAMP THE TENANT THIS ANSWER WAS SERVED FOR (owner report 2026-08-09: "I can see + # Nurilab's automations when logged into Royal Imports"). + # + # ⛔ THE SERVER WAS NEVER WRONG — MEASURED, link by link: per-tenant dataset repos, + # `get_runtime(claims["t"])` off the SIGNED cookie, and the `claim_tenant != pub["tenant"]` + # refusal above. The browser is what blends them: `aios_session` is ONE cookie at `path="/"` + # per ORIGIN, so signing into tenant B in a second tab silently repoints the FIRST tab. That + # tab goes on painting tenant A's chrome while every new request is answered for tenant B — + # and a WRITE from it lands in tenant B's store, which is the same event reported separately + # as "I updated the data and it doesn't register". + # + # It is stamped HERE rather than in a middleware because this is the one function every + # session-authed route passes through, so no route can be added that forgets it — and it is + # the only place that has already RESOLVED the tenant rather than guessed it. + # ⚠ The value is `claims["t"]`, the tenant the cookie was VERIFIED for — never + # `session.tenant` read back from something the request could influence. + response.headers[_TENANT_HEADER] = str(claims["t"]) + # R4: last AFTER the session is fully resolved — a stamp is only true of a request that was + # actually admitted, and putting it here means no failed-auth path can ever write one. + # qa-runner has no global account record. Never let the normal activity telemetry create or + # touch one through the default tenant-#0 users store. + if not user.get("qa_runner"): + _touch_active(user.get("username")) + return Session(tenant=claims["t"], user=user, claims=claims, runtime=rt) + + +def require_changes_session(request: Request, response: Response) -> Session | None: + """Authenticate the passive Pg change endpoint without reopening the database. + + Pg change tokens are intentionally disabled: a current client refreshes the data it is viewing + on focus, while an already-open legacy client may still call this route every ten seconds. A + verified signed cookie is enough to return that no-data response; resolving the account record + would itself turn those legacy requests into a permanent Neon keepalive. + """ + if store.backend() != "pg": + return require_session(request, response) + if request.headers.get("x-aios-change-check") == "focus-v1": + return require_session(request, response) + raw = request.cookies.get(aios_session.COOKIE_NAME) + claims = aios_session.read(raw) if raw else None + if not claims or not str(claims.get("t") or "").strip() or not str(claims.get("u") or "").strip(): + raise err(401, "invalid_session", "your session has expired. Sign in again") + return None + + +def module_gate(module_key): + """A dependency that 401s without a session and 403s without the grant for `module_key`.""" + def _dep(session: Session = Depends(require_session)) -> Session: + session.require(module_key) + return session + return _dep