diff --git "a/api/routes_external.py" "b/api/routes_external.py" --- "a/api/routes_external.py" +++ "b/api/routes_external.py" @@ -1,21 +1,508 @@ """Per-user credentials, governed reads and explicitly allowed bearer build tools.""" +import base64 import copy +import hashlib +import hmac +import importlib +import inspect import json +import time import uuid -from urllib.parse import quote +from urllib.parse import parse_qs, quote, urlencode, urlsplit, urlunsplit from fastapi import APIRouter, Body, Depends, Header, HTTPException, Request, Response +from fastapi.responses import JSONResponse, RedirectResponse from starlette.concurrency import run_in_threadpool import deps +import aios_session from deps import Session, err, require_session -from core import external_access, external_tools, sheets +from core import audit, external_access, external_oauth, external_tools, sheets +from harness import runtime router = APIRouter(prefix="/api/v1/external", tags=["external"]) -_CREDENTIAL_PREFIX = "lpb1." +_CREDENTIAL_PREFIXES = ("lpb1.", "lpc1.", "lpo1.", "lpr1.") +_QUERY_DEFAULT_LIMIT = 100 +_QUERY_MAX_LIMIT = 500 +_QUERY_MAX_SORTS = 8 +_QUERY_MAX_AGGREGATES = 16 +_QUERY_MAX_CURSOR = 768 +_QUERY_MAX_FILTER_DEPTH = 3 +_QUERY_MAX_FILTER_NODES = 100 +_QUERY_MAX_FILTER_SIBLINGS = 50 +_QUERY_KEYS = frozenset({"fields", "filters", "sorts", "limit", "cursor", "aggregates"}) +_VIEW_DRAFT_CONFIG_KEYS = frozenset({ + "filters", "filterConj", "sorts", "groupBy", "visible", "order", "display", + "memberPids", +}) +_CONFIRMATION_BUCKET = "external_confirmations" +_CONFIRMATION_TTL_SECONDS = 5 * 60 +_CONFIRMATION_MAX_BYTES = 512 * 1024 +_CONFIRMATION_PHRASE = "CONFIRM SCHEMA OR DESTRUCTIVE CHANGE" +_CONFIRMATION_PREFIX = "cfm1" + + +def _contains_credential(value) -> bool: + text = str(value or "") + return any(prefix in text for prefix in _CREDENTIAL_PREFIXES) + + +def _json_digest(value) -> str: + try: + encoded = json.dumps(value, sort_keys=True, separators=(",", ":"), + ensure_ascii=True, allow_nan=False, default=str) + except (TypeError, ValueError, OverflowError) as exc: + raise err(400, "query_arguments_invalid", + "The query contains a value that cannot be read safely.") from exc + return hashlib.sha256(encoded.encode("utf-8")).hexdigest() + + +def _canonical_json(value) -> bytes: + try: + encoded = json.dumps(value, sort_keys=True, separators=(",", ":"), + ensure_ascii=True, allow_nan=False) + except (TypeError, ValueError, OverflowError) as exc: + raise err(400, "tool_arguments_invalid", + "The tool arguments contain a value that cannot be represented safely.") from exc + raw = encoded.encode("utf-8") + if len(raw) > _CONFIRMATION_MAX_BYTES: + raise err(413, "confirmation_too_large", + "This change is too large for one preview. Split it into smaller changes.") + if _contains_credential(encoded): + raise err(400, "credential_in_arguments", + "Tool arguments must not contain credential values.") + return raw + + +def _b64(raw: bytes) -> str: + return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") + + +def _unb64(value: str) -> bytes: + return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4)) + + +class _PreviewRuntime: + """Lazy copy-on-write view of one tenant runtime; no method may reach a real writer. + + Existing Sheet/View/App writers therefore remain the validators and diff producers. Reads are + copied once, while every update/put is applied only to this private graph. Database CRUD uses + the separate pure planner below because those routes deliberately emit automation callbacks. + """ + + def __init__(self, real): + self._real = real + self._initial = {} + self._docs = {} + self._base_revisions = {} + self._local_revisions = {} + self.update_calls = 0 + + @property + def tenant(self): + return getattr(self._real, "tenant", None) + + def _load(self, name): + key = str(name) + if key not in self._docs: + try: + value = self._real.get(key, fresh=True) + except TypeError: + value = self._real.get(key) + value = copy.deepcopy(value) + self._initial[key] = copy.deepcopy(value) + self._docs[key] = value + try: + revision = self._real.revision(key) + except Exception: + revision = None + self._base_revisions[key] = copy.deepcopy(revision) + self._local_revisions[key] = 0 + return self._docs[key] + + def get(self, name, *args, **kwargs): + return copy.deepcopy(self._load(name)) + + def get_projection(self, name, drop=()): + value = self.get(name) + if isinstance(value, dict): + for key in drop or (): + value.pop(key, None) + return value + + def get_many(self, names): + return {str(name): self.get(name) for name in names or ()} + + def get_projections(self, names, drop=(), timeout_s=None): + return {str(name): self.get_projection(name, drop=drop) for name in names or ()} + + def update(self, name, callback, flush="sync", expect_rev=None, audit_row=None): + key = str(name) + current = copy.deepcopy(self._load(key)) + if expect_rev is not None: + base = self.revision(key) + if int((base or {}).get("rev") or 0) != int(expect_rev): + from core import view_audit + raise view_audit.ViewRevisionStale( + rev_current=int((base or {}).get("rev") or 0), + rev_sent=int(expect_rev), message="The preview revision is stale.") + next_value = callback(current) + self._docs[key] = copy.deepcopy(next_value) + self._local_revisions[key] += 1 + self.update_calls += 1 + return copy.deepcopy(next_value) + + def put(self, name, value): + key = str(name) + self._load(key) + self._docs[key] = copy.deepcopy(value) + self._local_revisions[key] += 1 + self.update_calls += 1 + return copy.deepcopy(value) + + def revision(self, name): + key = str(name) + self._load(key) + base = self._base_revisions.get(key) + rev = int((base or {}).get("rev") or 0) + self._local_revisions.get(key, 0) + return {"rev": rev, "token": _json_digest({"key": key, "rev": rev, + "base": base})} + + def available(self): + return bool(self._real.available()) if callable(getattr(self._real, "available", None)) else True + + def store_key(self, name): + fn = getattr(self._real, "store_key", None) + return fn(name) if callable(fn) else str(name) + + def changed(self): + return {key: {"before": copy.deepcopy(self._initial.get(key)), + "after": copy.deepcopy(value)} + for key, value in self._docs.items() + if self._initial.get(key) != value} + + def revision_binding(self): + return _json_digest({key: self._base_revisions.get(key) + for key in sorted(self._docs)}) + + def base_revisions(self): + return copy.deepcopy(self._base_revisions) + + def __getattr__(self, name): + # Read-only runtime capabilities (tenant config, mirror readers) remain available. Store + # writers are all named above and never fall through this proxy. + if name in {"upload_bytes", "delete_path", "flush"}: + raise AttributeError(name) + return getattr(self._real, name) + + +class _ConfirmationRuntime: + """Revision-guard every bucket the confirmed product writer may mutate.""" + + def __init__(self, real, expected): + self._real = real + self._expected = copy.deepcopy(expected if isinstance(expected, dict) else {}) + + @property + def tenant(self): + return getattr(self._real, "tenant", None) + + def update(self, name, callback, flush="sync", expect_rev=None, audit_row=None): + from core import view_audit + key = str(name) + revision = self._expected.get(key) + rev = revision.get("rev") if isinstance(revision, dict) else None + if type(rev) is not int: + raise view_audit.RevisionUnverifiable( + "The confirmed writer addressed a bucket outside its preview.") + if expect_rev is not None and int(expect_rev) != rev: + raise view_audit.ViewRevisionStale( + rev_current=rev, rev_sent=expect_rev, + message="The writer revision no longer matches its preview.") + answer = self._real.update( + key, callback, flush=flush, expect_rev=rev, audit_row=audit_row) + try: + self._expected[key] = copy.deepcopy(self._real.revision(key)) + except Exception: + self._expected[key] = {"rev": rev + 1} + return answer + + def put(self, name, value): + from core import view_audit + raise view_audit.RevisionUnverifiable( + "An unguarded document replacement cannot execute a confirmed change.") + + def __getattr__(self, name): + # Object-capability dispatchers receive this runtime too. They may read optional + # capability data, but no byte-store writer can join a document confirmation: it has + # neither the preview diff nor a revision guard. Refuse it rather than letting a future + # C5 operation turn this proxy into a side door around the guarded update above. + if name in {"upload_bytes", "delete_path", "flush"}: + raise AttributeError(name) + return getattr(self._real, name) + + +def _diff_documents(documents, *, limit=250): + changes = [] + + def walk(before, after, path): + if len(changes) >= limit or before == after: + return + if isinstance(before, dict) and isinstance(after, dict): + for key in sorted(before.keys() | after.keys(), key=str): + walk(before.get(key), after.get(key), [*path, str(key)]) + return + if isinstance(before, list) and isinstance(after, list): + for index in range(max(len(before), len(after))): + walk(before[index] if index < len(before) else None, + after[index] if index < len(after) else None, + [*path, str(index)]) + return + changes.append({"path": "/" + "/".join(path), + "before": copy.deepcopy(before), "after": copy.deepcopy(after)}) + + for bucket, pair in sorted(documents.items()): + walk(pair.get("before"), pair.get("after"), [bucket]) + return changes, len(changes) >= limit + + +def _credential_binding(session: Session) -> str: + claims = session.claims or {} + return str(claims.get("external_credential_id") or claims.get("external_key_id") or "") + + +def _confirmation_token(payload) -> str: + raw = _canonical_json(payload) + signature = aios_session._sign(b"external-confirm:v1:" + raw) + return f"{_CONFIRMATION_PREFIX}.{_b64(raw)}.{signature}" + + +def _read_confirmation_token(token) -> dict: + if not isinstance(token, str) or len(token) > _CONFIRMATION_MAX_BYTES * 2: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + try: + prefix, body, supplied = token.split(".", 2) + raw = _unb64(body) + expected = aios_session._sign(b"external-confirm:v1:" + raw) + if prefix != _CONFIRMATION_PREFIX or not hmac.compare_digest(supplied, expected): + raise ValueError("signature") + payload = json.loads(raw.decode("utf-8")) + except (ValueError, TypeError, UnicodeError, json.JSONDecodeError) as exc: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") from exc + if not isinstance(payload, dict) or payload.get("v") != 1: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + return payload + + +def _assert_finite_query_value(value) -> None: + """Keep non-finite source values from reaching sorting, aggregation, or a JSON response.""" + try: + json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True, + allow_nan=False, default=str) + except (TypeError, ValueError, OverflowError) as exc: + raise err(422, "query_value_invalid", + "A permitted record contains a value that cannot be represented safely.") from exc + + +def _cursor_proof(session: Session, query_digest: str, snapshot_digest: str, offset: int) -> str: + claims = session.claims or {} + binding = { + "tenant": session.tenant, + "user": session.uname, + "credential": claims.get("external_credential_id") or "browser", + "query": query_digest, + "snapshot": snapshot_digest, + "offset": offset, + "version": 1, + } + raw = json.dumps(binding, sort_keys=True, separators=(",", ":")).encode("utf-8") + return aios_session._sign(b"external-query:v1:" + raw) + + +def _encode_query_cursor(session: Session, query_digest: str, + snapshot_digest: str, offset: int) -> str: + payload = { + "v": 1, "q": query_digest, "s": snapshot_digest, "o": offset, + "p": _cursor_proof(session, query_digest, snapshot_digest, offset), + } + raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("ascii") + return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") + + +def _decode_query_cursor(session: Session, raw, query_digest: str, + snapshot_digest: str) -> int: + if not isinstance(raw, str) or not raw or len(raw) > _QUERY_MAX_CURSOR: + raise err(400, "query_cursor_invalid", "The query cursor is invalid.") + try: + padded = raw + "=" * (-len(raw) % 4) + payload = json.loads(base64.b64decode( + padded.encode("ascii"), altchars=b"-_", validate=True).decode("utf-8")) + except (ValueError, TypeError, UnicodeError, json.JSONDecodeError) as exc: + raise err(400, "query_cursor_invalid", "The query cursor is invalid.") from exc + if (not isinstance(payload, dict) + or set(payload) != {"v", "q", "s", "o", "p"} + or payload.get("v") != 1 + or type(payload.get("o")) is not int + or payload["o"] < 0 + or not isinstance(payload.get("q"), str) + or not isinstance(payload.get("s"), str) + or not isinstance(payload.get("p"), str)): + raise err(400, "query_cursor_invalid", "The query cursor is invalid.") + expected = _cursor_proof(session, payload["q"], payload["s"], payload["o"]) + if not hmac.compare_digest(payload["p"], expected): + raise err(400, "query_cursor_invalid", "The query cursor is invalid.") + if payload["q"] != query_digest or payload["s"] != snapshot_digest: + raise err(409, "query_cursor_stale", + "The query or its permitted result set changed. Start again without a cursor.") + return payload["o"] + + +def _sort_atom(value): + if isinstance(value, bool): + return "bool", 1 if value else 0 + if isinstance(value, (int, float)): + return "number", float(value) + if isinstance(value, str): + return "text", value.casefold(), value + return type(value).__name__, json.dumps(value, sort_keys=True, default=str, ensure_ascii=True) + + +def _sort_records(records, sorts): + ordered = list(records) + # Python's stable sort lets the first requested key remain the primary key when the rules + # are applied in reverse. Nulls stay last in both directions rather than floating to the top. + for rule in reversed(sorts): + field = rule["field"] + present = [row for row in ordered if row.get(field) is not None] + missing = [row for row in ordered if row.get(field) is None] + present.sort(key=lambda row: _sort_atom(row.get(field)), + reverse=rule["direction"] == "desc") + ordered = present + missing + return ordered + + +def _normalise_aggregates(raw, visible_keys): + if raw is None: + return [] + if not isinstance(raw, list) or len(raw) > _QUERY_MAX_AGGREGATES: + raise err(400, "query_aggregates_invalid", + f"aggregates must contain at most {_QUERY_MAX_AGGREGATES} operations.") + allowed = {"count", "count_distinct", "sum", "avg", "min", "max"} + out = [] + for item in raw: + if not isinstance(item, dict) or set(item) - {"fn", "field"}: + raise err(400, "query_aggregates_invalid", + "Every aggregate must contain only fn and an optional readable field.") + fn, field = item.get("fn"), item.get("field") + has_field = "field" in item + if (fn not in allowed + or (has_field and (not isinstance(field, str) or not field)) + or (fn != "count" and not has_field)): + raise err(400, "query_aggregates_invalid", + "Choose count, count_distinct, sum, avg, min, or max.") + if field is not None and field not in visible_keys: + raise err(400, "assistant_unknown_field", + "Every requested field must be readable in this database.") + out.append({"fn": fn, **({"field": field} if field is not None else {})}) + return out + + +def _assert_query_filter_bounds(raw) -> None: + """Reject an oversized tree before the shared strict filter validator recurses through it.""" + if raw is None: + return + if isinstance(raw, list): + roots = raw + elif isinstance(raw, dict): + roots = raw.get("nodes") + if not isinstance(roots, list): + return # The shared validator supplies the named shape refusal. + else: + return + if len(roots) > _QUERY_MAX_FILTER_SIBLINGS: + raise err(400, "query_filter_limit", + f"A filter group may contain at most {_QUERY_MAX_FILTER_SIBLINGS} conditions.") + stack = [(node, 1) for node in roots] + seen = 0 + while stack: + node, depth = stack.pop() + seen += 1 + if seen > _QUERY_MAX_FILTER_NODES: + raise err(400, "query_filter_limit", + f"A query may contain at most {_QUERY_MAX_FILTER_NODES} filter nodes.") + if not isinstance(node, dict) or "children" not in node: + continue + children = node.get("children") + if not isinstance(children, list): + continue + if len(children) > _QUERY_MAX_FILTER_SIBLINGS: + raise err(400, "query_filter_limit", + f"A filter group may contain at most {_QUERY_MAX_FILTER_SIBLINGS} conditions.") + if children and depth >= _QUERY_MAX_FILTER_DEPTH: + raise err(400, "query_filter_limit", + f"A filter may nest at most {_QUERY_MAX_FILTER_DEPTH} levels.") + stack.extend((child, depth + 1) for child in children) + + +def _aggregate_records(records, specs): + out = [] + for spec in specs: + fn, field = spec["fn"], spec.get("field") + values = ([row.get(field) for row in records if row.get(field) is not None] + if field is not None else []) + if fn == "count": + value = len(values) if field is not None else len(records) + elif fn == "count_distinct": + value = len({_json_digest(item) for item in values}) + elif fn in {"sum", "avg"}: + if any(isinstance(item, bool) or not isinstance(item, (int, float)) + for item in values): + raise err(400, "query_aggregate_type", + "sum and avg require a readable numeric field.") + value = sum(values) if fn == "sum" else (sum(values) / len(values) if values else None) + elif fn in {"min", "max"}: + value = (None if not values else + sorted(values, key=_sort_atom, reverse=fn == "max")[0]) + else: # Kept fail-closed even if the normalizer is changed independently. + raise err(400, "query_aggregates_invalid", "That aggregate is not available.") + out.append({**spec, "value": copy.deepcopy(value)}) + return out + + +def _view_referenced_fields(config) -> list[str]: + keys, seen = [], set() + + def add(value): + if isinstance(value, str) and value and value not in seen: + seen.add(value) + keys.append(value) + + def walk_filter(node): + if isinstance(node, list): + for child in node: + walk_filter(child) + elif isinstance(node, dict): + add(node.get("colId")) + rhs = node.get("rhs") + if isinstance(rhs, dict) and rhs.get("kind") != "stat": + add(rhs.get("colId")) + walk_filter(node.get("nodes")) + walk_filter(node.get("children")) + + if not isinstance(config, dict): + return keys + for name in ("visible", "order"): + for value in config.get(name) or (): + add(value) + add(config.get("groupBy")) + for rule in config.get("sorts") or (): + if isinstance(rule, dict): + add(rule.get("colId")) + walk_filter(config.get("filters")) + return keys def _key_scope(session): @@ -65,23 +552,52 @@ def _databases_in_arguments(value): return found -def _auth_refusal(): - raise err(401, external_access.AUTH_ERROR, "The credential is invalid or revoked.") +def _auth_refusal(request: Request | None = None): + challenge = "Bearer" + if request is not None: + metadata = _oauth_urls(request)["resource_metadata"] + challenge += f' resource_metadata="{metadata}"' + raise HTTPException( + status_code=401, + detail={"error": {"code": external_access.AUTH_ERROR, + "message": "The credential is invalid, expired, or revoked."}}, + headers={"WWW-Authenticate": challenge}, + ) def require_external_session( authorization: str | None = Header(default=None, alias="Authorization"), + request: Request = None, ) -> Session: """Resolve a bearer credential without consulting or extending the browser session cookie.""" if not isinstance(authorization, str): - _auth_refusal() + _auth_refusal(request) scheme, separator, token = authorization.strip().partition(" ") if not separator or scheme.lower() != "bearer" or not token.strip(): - _auth_refusal() + _auth_refusal(request) + raw_token = token.strip() try: - verified = external_access.verify(token.strip()) - except external_access.ExternalAuthError: - _auth_refusal() + if raw_token.startswith("lpo1."): + verified_oauth = external_oauth.verify_access( + raw_token, resource=_oauth_urls(request)["protected_resource"], + runtime_resolver=runtime.get_runtime) + claims = { + "t": verified_oauth.tenant, + "u": verified_oauth.user["username"], + "external": True, + "external_auth_type": "oauth", + "external_credential_id": verified_oauth.grant_id, + "external_client_id": verified_oauth.client_id, + "external_access": verified_oauth.access, + "external_databases": (external_access.ALL_DATABASES + if verified_oauth.databases == external_access.ALL_DATABASES + else list(verified_oauth.databases)), + } + return Session(verified_oauth.tenant, verified_oauth.user, claims, + verified_oauth.runtime) + verified = external_access.verify(raw_token) + except (external_access.ExternalAuthError, external_oauth.ExternalOAuthAuthError): + _auth_refusal(request) return Session( tenant=verified.tenant, user=verified.user, @@ -89,6 +605,8 @@ def require_external_session( "t": verified.tenant, "u": verified.user["username"], "external": True, + "external_auth_type": "api_key", + "external_credential_id": verified.key_id, "external_key_id": verified.key_id, "external_access": verified.access, "external_databases": (external_access.ALL_DATABASES @@ -124,6 +642,10 @@ def _management_refusal(exc: external_access.ExternalAccessError): raise err(400, exc.code, "Choose all databases, or name at least one database.") if exc.code == "external_label_invalid": raise err(400, exc.code, "Enter a label between 1 and 80 characters.") + if exc.code == "external_expiry_invalid": + raise err(400, exc.code, "Choose a future UTC expiry, or no expiry.") + if exc.code == "external_edit_empty": + raise err(400, exc.code, "Change at least one credential setting.") if exc.code == "external_key_not_found": raise err(404, exc.code, "That credential was not found.") if exc.code in {"external_identity_invalid", "external_account_unavailable"}: @@ -131,6 +653,34 @@ def _management_refusal(exc: external_access.ExternalAccessError): raise err(503, "external_access_unavailable", "The AI API is unavailable right now.") +def _oauth_management_refusal(exc: external_access.ExternalAccessError): + messages = { + "oauth_redirect_uri_invalid": "Use an exact HTTPS callback, or an HTTP loopback callback.", + "oauth_state_invalid": "The OAuth state must be a non-empty, high-entropy value.", + "oauth_state_replayed": "This OAuth state was already used. Start a new connection.", + "oauth_pkce_required": "This connection requires PKCE with S256.", + "oauth_scope_invalid": "The requested OAuth scope is not available for this connection.", + "oauth_response_type_invalid": "This server supports the authorization-code flow only.", + "oauth_client_invalid": "That OAuth client is unavailable.", + "oauth_client_not_found": "That OAuth client was not found.", + "oauth_connection_not_found": "That OAuth connection was not found.", + "oauth_edit_empty": "Change at least one OAuth client setting.", + "oauth_resource_invalid": "Use this MCP server's exact resource URL.", + } + if exc.code in messages: + status = 404 if exc.code in {"oauth_client_not_found", "oauth_connection_not_found"} else 400 + raise err(status, exc.code, messages[exc.code]) + if exc.code in {"external_access_scope_invalid", "external_databases_invalid", + "external_label_invalid"}: + _management_refusal(exc) + raise err(503, "oauth_unavailable", "OAuth is unavailable right now.") + + +def _credential_audit(kind: str, session: Session, credential_kind: str, **detail) -> None: + safe = {"surface": "ai_api", "credential_kind": credential_kind, **detail} + audit.record(kind, session.tenant, session.uname, safe) + + def _resolve_external_scope( session: Session, databases=None, @@ -197,8 +747,13 @@ def _markdown_inline(value) -> str: return " ".join(text.replace("`", "'").split()) -def _portable_skill_document(session: Session, base_url: str) -> str: - scoped = [ +def _portable_skill_document(session: Session | None, base_url: str) -> str: + """The skill.md an agent reads. With a session it carries that user's own read scope; with + None it is the PUBLIC document served at `/skill.md` (owner hotfix 2026-09-23, Monid's + `set up /SKILL.md`), which names no tenant, database or field and sends the agent to + discover its scope after it authenticates.""" + public = session is None + scoped = [] if public else [ row for row in _resolve_external_scope(session, include_schema=True) if row["permitted"] ] @@ -207,6 +762,35 @@ def _portable_skill_document(session: Session, base_url: str) -> str: example = scoped[0] surface_url = f"{base_url.rstrip('/')}/api/v1/external" + connect = [ + "## Set up", + "", + "Connect once, with the Loopable sign-in (remote MCP over OAuth) or with an API key.", + "", + f"MCP server URL: `{surface_url}/mcp`", + "", + "Claude Code:", + "", + "```sh", + f"claude mcp add --transport http loopable {surface_url}/mcp", + "```", + "", + "Then run `/mcp` in Claude Code and finish the Loopable sign-in in the browser.", + "", + "Codex:", + "", + "```sh", + f"codex mcp add loopable --url {surface_url}/mcp", + "codex mcp login loopable", + "```", + "", + ("Cursor: add `{\"mcpServers\": {\"loopable\": {\"url\": \"" + surface_url + "/mcp\"}}}` " + "to `~/.cursor/mcp.json`, keeping any existing servers, then finish the Loopable sign-in."), + "", + ("For code or an SDK, ask the user to create an API key in Loopable under AI API and to " + "store it in an environment variable. Never ask for the key in chat and never print it."), + "", + ] if public else [] lines = [ "---", "name: loopable-external-data", @@ -230,6 +814,7 @@ def _portable_skill_document(session: Session, base_url: str) -> str: "", f"Base URL: `{surface_url}`", "", + *connect, "## First call: list databases", "", "Endpoint: `GET /api/v1/external/databases`", @@ -286,6 +871,27 @@ def _portable_skill_document(session: Session, base_url: str) -> str: "answerable right now. The reason appears in the scope below."), "", ]) + elif public: + lines.extend([ + "```sh", + "curl --request GET \\", + " --header 'Authorization: Bearer ' \\", + f" '{surface_url}/databases/{{database}}/schema'", + "```", + "", + "## Query a database", + "", + "Endpoint: `POST /api/v1/external/databases/{database}/query`", + "", + "```sh", + "curl --request POST \\", + " --header 'Authorization: Bearer ' \\", + " --header 'Content-Type: application/json' \\", + " --data '{\"fields\":[\"\"],\"filters\":null}' \\", + f" '{surface_url}/databases/{{database}}/query'", + "```", + "", + ]) else: lines.extend([ "No schema call is available because this user's current scope has no databases.", @@ -298,8 +904,18 @@ def _portable_skill_document(session: Session, base_url: str) -> str: "", ]) - lines.extend(["## This user's current read scope", ""]) - if not scoped: + if public: + lines.extend([ + "## Your read scope", + "", + ("Loopable answers only with what the signed-in user may already read in the app. " + "After connecting, call `GET /databases` for the databases, then " + "`GET /databases/{database}/schema` for the fields each one exposes, before any query."), + "", + ]) + else: + lines.extend(["## This user's current read scope", ""]) + if not scoped and not public: lines.extend(["No databases are currently permitted.", ""]) for row in scoped: database = _markdown_inline(row["database"]) @@ -359,7 +975,7 @@ def _portable_skill_document(session: Session, base_url: str) -> str: "", ("Sheet tools require analyst and sheets grants. Geometry patches carry the revision " "read by the server; pass rev to also protect the revision you read. Cell writes " - "return accepted and refused addresses, retaining the app's partial-write behavior."), + "are previewed before confirmation. A partially refused patch changes no cells."), "", ("View tools use the grid's native config: filters, sorts, groupBy, visible and display. " "Fields omitted from visible are hidden. The grid validates the config. App tools use " @@ -393,7 +1009,7 @@ def _portable_skill_document(session: Session, base_url: str) -> str: "", ]) document = "\n".join(lines) - if _CREDENTIAL_PREFIX in document: + if _contains_credential(document): raise RuntimeError("portable skill document contained a credential value") return document @@ -405,11 +1021,16 @@ def create_key(body=Body(default=None), session: Session = Depends(require_sessi label = body.get("label") if isinstance(body, dict) else None access = body.get("access") if isinstance(body, dict) else None databases = body.get("databases") if isinstance(body, dict) else None + expires_at = body.get("expires_at") if isinstance(body, dict) else None try: key, token = external_access.mint(session.runtime, session.uname, session.tenant, label, - access=access, databases=databases) + access=access, databases=databases, + expires_at=expires_at) except external_access.ExternalAccessError as exc: _management_refusal(exc) + _credential_audit("credential.added", session, "api_key", access=key["access"], + resource_mode="all" if key["databases"] == "all" else "allowlist", + resource_count=(0 if key["databases"] == "all" else len(key["databases"]))) return {"key": key, "secret": token} @@ -423,6 +1044,36 @@ def list_keys(session: Session = Depends(require_session)): return {"keys": keys, "can_mint": _can_use_analyst(session)} +@router.patch("/keys/{key_id}") +def edit_key(key_id: str, body=Body(default=None), session: Session = Depends(require_session)): + """Edit metadata and narrowing scope without ever reading or replacing the secret.""" + if not isinstance(body, dict): + raise err(400, "external_edit_empty", "Change at least one credential setting.") + allowed = {"label", "access", "databases", "expires_at"} + if not body or set(body) - allowed: + raise err(400, "external_edit_invalid", "Only label, access, databases, and expiry can be changed.") + kwargs = {key: body[key] for key in allowed if key in body} + try: + key = external_access.edit(session.runtime, session.uname, session.tenant, key_id, **kwargs) + except external_access.ExternalAccessError as exc: + _management_refusal(exc) + _credential_audit("config.changed", session, "api_key", setting="credential_metadata", + access=key["access"], + resource_mode="all" if key["databases"] == "all" else "allowlist") + return {"key": key} + + +@router.post("/keys/{key_id}/rotate") +def rotate_key(key_id: str, session: Session = Depends(require_session)): + """Atomically invalidate the old secret and reveal its replacement once.""" + try: + key, token = external_access.rotate(session.runtime, session.uname, session.tenant, key_id) + except external_access.ExternalAccessError as exc: + _management_refusal(exc) + _credential_audit("credential.rotated", session, "api_key", reason="user_rotation") + return {"key": key, "secret": token} + + @router.post("/keys/{key_id}/revoke") def revoke_key(key_id: str, session: Session = Depends(require_session)): """Tombstone one key owned by the signed-in human. Bearer auth is not accepted here.""" @@ -430,9 +1081,300 @@ def revoke_key(key_id: str, session: Session = Depends(require_session)): key = external_access.revoke(session.runtime, session.uname, session.tenant, key_id) except external_access.ExternalAccessError as exc: _management_refusal(exc) + _credential_audit("credential.revoked", session, "api_key", reason="user_revoke") return {"key": key} +def _oauth_urls(request: Request) -> dict: + origin = str(request.base_url).rstrip("/") + root = origin + "/api/v1/external" + return { + "issuer": root, + "authorization_endpoint": root + "/oauth/authorize", + "token_endpoint": root + "/oauth/token", + "registration_endpoint": root + "/oauth/clients", + "revocation_endpoint": root + "/oauth/disconnect", + "protected_resource": root + "/mcp", + "metadata": origin + "/.well-known/oauth-authorization-server/api/v1/external", + "resource_metadata": (origin + + "/.well-known/oauth-protected-resource/api/v1/external/mcp"), + } + + +def _require_oauth_resource(request: Request, value) -> str: + """Bind every grant and token request to this exact remote MCP audience.""" + supplied = external_oauth.normalise_resource(value) + expected = external_oauth.normalise_resource(_oauth_urls(request)["protected_resource"]) + if supplied != expected: + raise external_oauth.ExternalOAuthError("oauth_resource_invalid") + return expected + + +@router.get("/.well-known/oauth-authorization-server") +def oauth_server_metadata(request: Request): + """Public authorization-server discovery for the path-scoped remote MCP issuer.""" + urls = _oauth_urls(request) + return { + "issuer": urls["issuer"], + "authorization_endpoint": urls["authorization_endpoint"], + "token_endpoint": urls["token_endpoint"], + "revocation_endpoint": urls["revocation_endpoint"], + "response_types_supported": ["code"], + "grant_types_supported": ["authorization_code", "refresh_token"], + "token_endpoint_auth_methods_supported": ["none"], + "code_challenge_methods_supported": ["S256"], + "scopes_supported": list(external_oauth.SCOPES), + } + + +@router.get("/.well-known/oauth-protected-resource") +def oauth_resource_metadata(request: Request): + """Public protected-resource metadata; it contains endpoints, never a client secret.""" + urls = _oauth_urls(request) + return { + "resource": urls["protected_resource"], + "authorization_servers": [urls["issuer"]], + "scopes_supported": list(external_oauth.SCOPES), + "bearer_methods_supported": ["header"], + } + + +@router.get("/oauth/metadata") +def oauth_metadata(request: Request): + return {"authorization_server": oauth_server_metadata(request), + "protected_resource": oauth_resource_metadata(request)} + + +@router.post("/oauth/clients", status_code=201) +def create_oauth_client(body=Body(default=None), session: Session = Depends(require_session)): + """Register one user-owned public client; PKCE replaces a shared client secret.""" + session.require("analyst") + body = body if isinstance(body, dict) else {} + try: + client = external_oauth.register_client( + session.runtime, session.uname, session.tenant, body.get("label"), + body.get("redirect_uris"), access=body.get("access"), + databases=body.get("databases"), + ) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + _credential_audit("config.changed", session, "oauth_client", setting="client_registered", + access=client["access"]) + return {"client": client} + + +@router.get("/oauth/clients") +def list_oauth_clients(session: Session = Depends(require_session)): + try: + clients = external_oauth.list_clients(session.runtime, session.uname, session.tenant) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + return {"clients": clients, "can_connect": _can_use_analyst(session)} + + +@router.patch("/oauth/clients/{client_id}") +def edit_oauth_client(client_id: str, body=Body(default=None), + session: Session = Depends(require_session)): + if not isinstance(body, dict): + raise err(400, "oauth_edit_empty", "Change at least one OAuth client setting.") + allowed = {"label", "redirect_uris", "access", "databases"} + if not body or set(body) - allowed: + raise err(400, "oauth_edit_invalid", "Only label, callbacks, access, and resources can be changed.") + try: + client = external_oauth.edit_client( + session.runtime, session.uname, session.tenant, client_id, + **{key: body[key] for key in allowed if key in body}, + ) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + _credential_audit("config.changed", session, "oauth_client", setting="client_metadata", + access=client["access"]) + return {"client": client} + + +def _oauth_redirect(uri: str, **params): + parts = urlsplit(uri) + query = parse_qs(parts.query, keep_blank_values=True) + for key, value in params.items(): + query[key] = [str(value)] + location = urlunsplit((parts.scheme, parts.netloc, parts.path, + urlencode(query, doseq=True), parts.fragment)) + return RedirectResponse(location, status_code=302) + + +@router.get("/oauth/callback") +@router.get("/oauth/authorize") +def oauth_authorize( + request: Request, + response_type: str, + client_id: str, + redirect_uri: str, + state: str, + code_challenge: str, + code_challenge_method: str, + resource: str, + scope: str | None = None, + session: Session = Depends(require_session), +): + """Authorize the signed-in user and redirect an exact registered callback with one code.""" + session.require("analyst") + try: + audience = _require_oauth_resource(request, resource) + result = external_oauth.authorize( + session.runtime, session.uname, session.tenant, client_id=client_id, + redirect_uri=redirect_uri, state=state, code_challenge=code_challenge, + code_challenge_method=code_challenge_method, resource=audience, scope=scope, + response_type=response_type, + ) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + return _oauth_redirect(result["redirect_uri"], code=result["code"], state=result["state"]) + + +async def _oauth_token_body(request: Request) -> dict: + raw = await request.body() + if len(raw) > 16_384: + raise external_oauth.ExternalOAuthError("oauth_request_invalid") + content_type = request.headers.get("content-type", "").split(";", 1)[0].strip().lower() + if content_type == "application/json": + try: + value = json.loads(raw or b"{}") + except (TypeError, ValueError, UnicodeError) as exc: + raise external_oauth.ExternalOAuthError("oauth_request_invalid") from exc + if not isinstance(value, dict): + raise external_oauth.ExternalOAuthError("oauth_request_invalid") + return value + try: + parsed = parse_qs(raw.decode("utf-8"), keep_blank_values=True, strict_parsing=True) + except (UnicodeError, ValueError) as exc: + raise external_oauth.ExternalOAuthError("oauth_request_invalid") from exc + return {key: values[-1] for key, values in parsed.items()} + + +def _oauth_token_error(code: str): + public = "invalid_grant" if code in { + "oauth_invalid_grant", "oauth_refresh_replayed", "oauth_refresh_exhausted", + external_access.AUTH_ERROR, + } else "invalid_target" if code == "oauth_resource_invalid" else "invalid_request" + description = ("The authorization grant is invalid, expired, replayed, or revoked." + if public == "invalid_grant" else "The OAuth token request is invalid.") + return JSONResponse({"error": public, "error_description": description}, status_code=400, + headers={"Cache-Control": "no-store", "Pragma": "no-cache"}) + + +@router.post("/oauth/token") +async def oauth_token(request: Request): + """Cookie-free authorization-code exchange and rotating refresh-token endpoint.""" + try: + body = await _oauth_token_body(request) + grant_type = body.get("grant_type") + audience = _require_oauth_resource(request, body.get("resource")) + if grant_type == "authorization_code": + result = external_oauth.exchange_code( + body.get("code"), client_id=body.get("client_id"), + redirect_uri=body.get("redirect_uri"), code_verifier=body.get("code_verifier"), + resource=audience, runtime_resolver=runtime.get_runtime, + ) + verified = external_oauth.verify_access( + result["access_token"], resource=audience, runtime_resolver=runtime.get_runtime) + audit.record("credential.added", verified.tenant, verified.user["username"], + {"surface": "ai_api", "credential_kind": "oauth"}) + elif grant_type == "refresh_token": + result = external_oauth.refresh( + body.get("refresh_token"), client_id=body.get("client_id"), + resource=audience, runtime_resolver=runtime.get_runtime) + verified = external_oauth.verify_access( + result["access_token"], resource=audience, runtime_resolver=runtime.get_runtime) + audit.record("credential.rotated", verified.tenant, verified.user["username"], + {"surface": "ai_api", "credential_kind": "oauth", + "reason": "refresh_rotation"}) + else: + raise external_oauth.ExternalOAuthError("oauth_request_invalid") + except external_access.ExternalAccessError as exc: + return _oauth_token_error(exc.code) + response = JSONResponse(result) + response.headers.update({"Cache-Control": "no-store", "Pragma": "no-cache"}) + return response + + +@router.post("/oauth/disconnect") +def oauth_disconnect( + authorization: str | None = Header(default=None, alias="Authorization"), +): + """Cookie-free immediate revocation using the access or refresh token itself.""" + if not isinstance(authorization, str): + _auth_refusal() + scheme, separator, token = authorization.strip().partition(" ") + if not separator or scheme.lower() != "bearer" or not token.strip(): + _auth_refusal() + try: + stopped = external_oauth.disconnect(token.strip(), runtime_resolver=runtime.get_runtime) + except external_oauth.ExternalOAuthAuthError: + _auth_refusal() + audit.record("credential.revoked", stopped.tenant, stopped.username, + {"surface": "ai_api", "credential_kind": "oauth", + "reason": "disconnect"}) + return {"connection": stopped.connection} + + +@router.get("/oauth/connections") +def oauth_connections(session: Session = Depends(require_session)): + try: + connections = external_oauth.list_connections( + session.runtime, session.uname, session.tenant) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + return {"connections": connections} + + +@router.post("/oauth/connections/{connection_id}/disconnect") +def oauth_disconnect_human(connection_id: str, session: Session = Depends(require_session)): + try: + connection = external_oauth.disconnect_for_user( + session.runtime, session.uname, session.tenant, connection_id) + except external_access.ExternalAccessError as exc: + _oauth_management_refusal(exc) + _credential_audit("credential.revoked", session, "oauth", reason="user_disconnect") + return {"connection": connection} + + +@router.get("/setup") +def external_setup(request: Request): + """Secret-free client-specific setup metadata for the AI API page.""" + urls = _oauth_urls(request) + starter = ("List the Loopable databases I can access, describe the fields in the one I choose, " + "and ask before querying any records. Do not make changes.") + caveat = ("Client availability, plan eligibility, and workspace approval depend on the AI " + "client. Check with that client's workspace administrator.") + mcp = urls["protected_resource"] + return { + "mcp_url": mcp, + "oauth": {"metadata_url": urls["metadata"], "client_registration": urls["registration_endpoint"], + "steps": ["Register this client's exact callback in Loopable.", + "Open the authorization URL and approve as the signed-in Loopable user.", + "Send the MCP URL as resource on authorization and token requests.", + "Exchange the code with PKCE S256; never paste a token into chat."]}, + "code_sdk": {"authentication": "Bearer API key from an environment variable", + "header": "Authorization: Bearer ${LOOPABLE_API_KEY}", + "base_url": urls["issuer"], + "warning": "The key is revealed only on create or rotate. Store it in a secret manager."}, + "clients": { + "claude": {"mcp_url": mcp, + "command_or_config": f"claude mcp add --transport http loopable {mcp}", + "plan_admin_caveat": caveat, "starter_prompt": starter}, + "chatgpt": {"mcp_url": mcp, + "command_or_config": "Add a custom remote MCP connector and enter the MCP URL; complete OAuth in the opened browser.", + "plan_admin_caveat": caveat, "starter_prompt": starter}, + "claude_code": {"mcp_url": mcp, + "command_or_config": f"claude mcp add --transport http loopable {mcp}", + "plan_admin_caveat": caveat, "starter_prompt": starter}, + "codex": {"mcp_url": mcp, + "command_or_config": f"codex mcp add loopable --url {mcp}", + "plan_admin_caveat": caveat, "starter_prompt": starter}, + }, + } + + @router.get("/skill.md") def portable_skill(request: Request, session: Session = Depends(require_session)): """Download current governed external read and build instructions.""" @@ -453,7 +1395,10 @@ def whoami(session: Session = Depends(require_external_analyst)): "username": session.uname, "name": session.user.get("name") or session.uname, "tenant": session.tenant, - "key_id": session.claims["external_key_id"], + "auth_type": session.claims.get("external_auth_type", "api_key"), + "credential_id": session.claims.get("external_credential_id"), + "key_id": session.claims.get("external_key_id"), + "client_id": session.claims.get("external_client_id"), "access": access, "databases": (external_access.ALL_DATABASES if databases == external_access.ALL_DATABASES else list(databases)), @@ -468,19 +1413,19 @@ def scope_databases(session: Session = Depends(require_session)): return {"databases": [ {key: row[key] for key in ("database", "label", "permitted", "answerable")} for row in _resolve_external_scope(session) - if row.get("permitted") or row.get("visible") + if row.get("permitted") ]} @router.get("/databases") def list_databases(session: Session = Depends(require_external_analyst)): - """List only sources this user may read or already sees elsewhere in the product.""" + """List only sources this user may currently read through the ordinary permission wall.""" databases = [] key_databases = _key_scope(session)[1] for row in _resolve_external_scope(session): if not external_access.database_allowed(key_databases, row["database"]): continue - if not (row.get("permitted") or row.get("visible")): + if not row.get("permitted"): continue public = { "database": row["database"], @@ -510,15 +1455,124 @@ def query_database( body: dict | None = Body(default=None), session: Session = Depends(require_external_analyst), ): - """Read one detached Assistant snapshot; FastAPI rejects non-object request bodies.""" + """Read one freshly permissioned, bounded and cursor-stable Assistant snapshot.""" + return _query_database(session, database, body or {}) + + +def _query_database(session: Session, database: str, payload: dict): + if not isinstance(payload, dict) or set(payload) - _QUERY_KEYS: + raise err(400, "query_arguments_invalid", + "Use only fields, filters, sorts, limit, cursor, and aggregates.") _assert_database_scope(session, database) - payload = body or {} - return deps.assistant_read_scope( - session, - database, - fields=payload.get("fields"), - filters=payload.get("filters"), - ) + limit = payload.get("limit", _QUERY_DEFAULT_LIMIT) + if type(limit) is not int or not 1 <= limit <= _QUERY_MAX_LIMIT: + raise err(400, "query_limit_invalid", + f"limit must be between 1 and {_QUERY_MAX_LIMIT}.") + raw_sorts = payload.get("sorts") or [] + if not isinstance(raw_sorts, list) or len(raw_sorts) > _QUERY_MAX_SORTS: + raise err(400, "query_sorts_invalid", + f"sorts must contain at most {_QUERY_MAX_SORTS} rules.") + _assert_query_filter_bounds(payload.get("filters")) + + # This is the same permissioned record reader the in-app Assistant uses. It resolves the + # database, field and row walls on every call before this adapter sorts, caps, or aggregates. + scoped = deps.assistant_read_scope( + session, database, fields=None, filters=payload.get("filters")) + visible_fields = list(scoped.get("fields") or []) + visible_keys = { + field.get("key") for field in visible_fields + if isinstance(field, dict) and isinstance(field.get("key"), str) + } + requested = payload.get("fields") + if requested is None: + selected_keys = [field["key"] for field in visible_fields if field.get("key") in visible_keys] + else: + if (not isinstance(requested, list) or len(requested) > 200 + or any(not isinstance(key, str) or not key or key not in visible_keys + for key in requested)): + raise err(400, "assistant_unknown_field", + "Every requested field must be readable in this database.") + selected_keys = list(dict.fromkeys(requested)) + + sorts = [] + for rule in raw_sorts: + if (not isinstance(rule, dict) or set(rule) != {"field", "direction"} + or rule.get("field") not in visible_keys + or rule.get("direction") not in {"asc", "desc"}): + # Hidden, unknown and malformed sort fields deliberately share one refusal. A guessed + # field must never become an existence oracle at this external boundary. + raise err(400, "assistant_unknown_field", + "Every requested field must be readable in this database.") + sorts.append({"field": rule["field"], "direction": rule["direction"]}) + aggregates = _normalise_aggregates(payload.get("aggregates"), visible_keys) + + rows = list(scoped.get("records") or []) + inspected_keys = (set(selected_keys) + | {rule["field"] for rule in sorts} + | {spec["field"] for spec in aggregates if spec.get("field") is not None}) + for row in rows: + _assert_finite_query_value({ + "pid": row.get("pid"), + **{key: row.get(key) for key in inspected_keys}, + }) + rows = _sort_records(rows, sorts) + query_digest = _json_digest({ + "database": database, "fields": selected_keys, "filters": scoped.get("filters"), + "sorts": sorts, "aggregates": aggregates, "limit": limit, + }) + # Bind a cursor to the live permission projection as well as the source revision. A field or + # row-scope revocation changes this hash on the next call, so an old page cannot skip into a + # newly narrowed result set. Only the digest enters the cursor; no record id or value does. + snapshot_digest = _json_digest({ + "source_version": scoped.get("source_version"), + "visible_fields": [field["key"] for field in visible_fields + if isinstance(field, dict) and field.get("key") in visible_keys], + "permitted_pids": [row.get("pid") for row in rows], + }) + offset = (0 if payload.get("cursor") is None else + _decode_query_cursor(session, payload.get("cursor"), + query_digest, snapshot_digest)) + if offset > len(rows): + raise err(409, "query_cursor_stale", + "The permitted result set changed. Start again without a cursor.") + page_rows = rows[offset:offset + limit] + records = [ + {"pid": copy.deepcopy(row.get("pid")), + **{key: copy.deepcopy(row.get(key)) for key in selected_keys}} + for row in page_rows + ] + next_offset = offset + len(page_rows) + next_cursor = (_encode_query_cursor(session, query_digest, snapshot_digest, next_offset) + if next_offset < len(rows) else None) + result = { + "database": scoped.get("database"), + "label": scoped.get("label"), + "source_kind": scoped.get("source_kind"), + "source_version": copy.deepcopy(scoped.get("source_version")), + "retrieved_at": scoped.get("retrieved_at"), + "permission_scope_applied": True, + "fields": [copy.deepcopy(field) for field in visible_fields + if field.get("key") in selected_keys], + "filters": copy.deepcopy(scoped.get("filters")), + "sorts": copy.deepcopy(sorts), + "records": records, + "aggregates": _aggregate_records(rows, aggregates), + "page": {"limit": limit, "returned": len(records), "offset": offset, + "has_more": next_cursor is not None, "next_cursor": next_cursor}, + "caps": {"max_page_size": _QUERY_MAX_LIMIT, "max_sorts": _QUERY_MAX_SORTS, + "max_aggregates": _QUERY_MAX_AGGREGATES, + "max_filter_depth": _QUERY_MAX_FILTER_DEPTH, + "max_filter_nodes": _QUERY_MAX_FILTER_NODES, + "max_filter_siblings": _QUERY_MAX_FILTER_SIBLINGS}, + } + _assert_finite_query_value(result) + audit.record("external.query", session.tenant, session.uname, { + "surface": "ai_api", "authentication": session.claims.get("external_auth_type", "api_key"), + "field_count": len(selected_keys), "filter_applied": scoped.get("filters") is not None, + "sort_count": len(sorts), "aggregate_count": len(aggregates), + "page_size": limit, "returned_count": len(records), "cursor_used": offset > 0, + }) + return result def _view_context(session, database, event): @@ -583,15 +1637,148 @@ def _application_access(session, databases, *, strict=False): return allowed, records +def _validate_personal_view_draft(session: Session, database: str, raw: dict) -> None: + if (not isinstance(raw, dict) or set(raw) - {"id", "name", "config", "note"} + or not isinstance(raw.get("config"), dict) + or set(raw["config"]) - _VIEW_DRAFT_CONFIG_KEYS): + raise err(400, "tool_arguments_invalid", + "A personal draft View may contain only id, name, note, and the published config fields.") + if (not isinstance(raw.get("id"), str) or not 1 <= len(raw["id"]) <= 120 + or raw["id"] != raw["id"].strip() + or not isinstance(raw.get("name"), str) or not 1 <= len(raw["name"]) <= 120 + or raw["name"] != raw["name"].strip() + or ("note" in raw and (not isinstance(raw["note"], str) + or len(raw["note"]) > 2_000))): + raise err(400, "tool_arguments_invalid", + "A personal draft View needs bounded id, name, and optional note text.") + config = raw["config"] + for name in ("visible", "order"): + value = config.get(name, []) + if not isinstance(value, list) or len(value) > 400 or any(not isinstance(key, str) for key in value): + raise err(400, "tool_arguments_invalid", + f"View {name} must be a bounded list of readable field keys.") + sorts = config.get("sorts", []) + if (not isinstance(sorts, list) or len(sorts) > 20 + or any(not isinstance(rule, dict) + or set(rule) - {"colId", "dir", "locked"} + or not isinstance(rule.get("colId"), str) + or rule.get("dir") not in {"asc", "desc"} + or ("locked" in rule and type(rule["locked"]) is not bool) + for rule in sorts)): + raise err(400, "tool_arguments_invalid", + "View sorts must use readable fields and asc or desc direction.") + if config.get("filterConj") not in (None, "and", "or"): + raise err(400, "tool_arguments_invalid", "View filterConj must be and or or.") + if config.get("groupBy") is not None and not isinstance(config.get("groupBy"), str): + raise err(400, "tool_arguments_invalid", "View groupBy must be a readable field key.") + if config.get("display") is not None and not isinstance(config.get("display"), dict): + raise err(400, "tool_arguments_invalid", "View display must be an object.") + member_pids = config.get("memberPids", []) + if (not isinstance(member_pids, list) or len(member_pids) > 10_000 + or any(type(pid) not in (int, str) or not str(pid).strip() for pid in member_pids)): + raise err(400, "tool_arguments_invalid", + "View memberPids must be a bounded list of record ids.") + + _assert_query_filter_bounds(config.get("filters")) + schema = database_schema(database, session) + visible = { + field.get("key") for field in schema.get("fields") or () + if isinstance(field, dict) and isinstance(field.get("key"), str) + } + if any(key not in visible for key in _view_referenced_fields(config)): + raise err(400, "assistant_unknown_field", + "Every requested field must be readable in this database.") + # The ordinary Assistant validator owns filter syntax and operands. fields=[] keeps values + # out of this validation result while still applying the live database/field/row walls. + filters = config.get("filters") + deps.assistant_read_scope( + session, database, fields=[], filters=None if filters == [] else filters) + + +def _view_share_preview(session: Session, args: dict): + """Build C8's audience/field-inheritance plan without changing a View or any grant.""" + import routes_shares + + database, view_id = args["database"], str(args["view_id"] or "").strip() + entries = args["entries"] + _assert_database_scope(session, database) + if not view_id or len(view_id) > 120 or view_id != args["view_id"]: + raise err(400, "tool_arguments_invalid", + "A View id must have 1 to 120 characters without surrounding spaces.") + if (not isinstance(entries, list) or len(entries) > 200 + or any(not isinstance(row, dict) or set(row) != {"user", "role"} + or not isinstance(row.get("user"), str) + or row.get("role") not in {"view", "edit"} for row in entries)): + raise err(400, "bad_entries", "entries must be a bounded list of {user, role}.") + routes_shares._entries_or_400(session, entries) + + ctx = _view_context(session, database, {}) + found = ctx.table.find_view(view_id, prefer_owner=session.uname) + if not found or str(found[0]).strip().lower() != str(session.uname).strip().lower(): + raise err(404, "view_unavailable", + "That personal draft View is unavailable.") + view = found[1] + current = routes_shares.get_share("view", view_id, session) + if current.get("owner") or current.get("entries"): + raise err(409, "view_is_shared", + "This View is already shared. Use a separately confirmed View audience change.") + schema = database_schema(database, session) + readable = { + field.get("key") for field in schema.get("fields") or () + if isinstance(field, dict) and isinstance(field.get("key"), str) + } + included = routes_shares._view_field_keys(view) + if any(key not in readable for key in included): + raise err(409, "view_permission_changed", + "This View includes a field you can no longer read. Update the draft before sharing.") + + # Use the same C8 preparation as the share writer. Preview validates private/shared + # definitions and the caller's field wall, but never promotes definitions or writes grants. + try: + topic, _view, _grant_topic, included, _count = routes_shares._prepare_view_share( + session, view_id, preview=True) + except routes_shares._ViewSharePreparationError as exc: + raise err(409, "view_permission_changed", + "This View includes a field you can no longer share. Update the draft first.") from exc + if f"{topic}_table_workspace" != ctx.table.table_key or _view != view: + raise err(409, "view_permission_changed", + "This View changed while its sharing preview was prepared. Open the draft again.") + definitions = routes_shares._view_field_definitions( + session, f"{topic}_table_workspace", included) + database_owned = [key for key in included + if not isinstance(definitions[key][0], dict) + or definitions[key][1] == "catalogue"] + return { + "preview": True, + "mutated": False, + "database": database, + "view_id": view_id, + "draft": "personal", + "current_entries": copy.deepcopy(current.get("entries") or []), + "proposed_entries": copy.deepcopy(entries), + "field_inheritance": { + "included": included, + "database_owned": database_owned, + "grantable": included, + "refused": [], + "scope": "view_audience", + "retains_recipient_permission_walls": True, + }, + "requires_confirmation": True, + "next_tool": "confirm_change", + } + + def _view_event(session, kind, args): from core import grid_events database = args["database"] _assert_database_scope(session, database) - event = {"id": uuid.uuid4().hex, "type": kind} + from core import write_execution + event = {"id": write_execution.new_id(), "type": kind} if kind == "view_upsert": raw = args["view"] - if (not isinstance(raw.get("config"), dict) + if (not isinstance(raw, dict) or not isinstance(raw.get("config"), dict) or not isinstance(raw.get("id"), str) or not raw["id"].strip() or not isinstance(raw.get("name"), str) or not raw["name"].strip()): raise err(400, "tool_arguments_invalid", "A View needs an id, a name and an object config.") @@ -606,6 +1793,21 @@ def _view_event(session, kind, args): if not view_id.strip() or len(view_id) > 120 or view_id != view_id.strip(): raise err(400, "tool_arguments_invalid", "A View id must have 1 to 120 characters without surrounding spaces.") ctx = _view_context(session, database, event) + if kind == "view_upsert": + # Resolve the ordinary View/database wall before the additional T31 draft validation so + # the established refusal vocabulary and connector record-scope guard stay intact. + _validate_personal_view_draft(session, database, raw) + existing = ctx.table.find_view(view_id, prefer_owner=session.uname) + if (existing and str(existing[0]).strip().lower() + != str(session.uname).strip().lower()): + raise err(404, "view_unavailable", + f"View {view_id}: another user's personal draft is read-only.") + from core import shares + share_record = shares.grants("view", view_id, st=session.runtime) + if share_record.get("owner") or share_record.get("entries"): + raise err(409, "view_is_shared", + "This View has entered the sharing workflow and cannot be changed by the " + "personal-draft tool. Use a separately confirmed View change.") try: before = ctx.table.find_view(view_id, prefer_owner=session.uname) rerender = grid_events.handle_one(event, ctx) @@ -633,7 +1835,12 @@ def _view_event(session, kind, args): # after is the only thing that can tell that apart from a save that landed # ([[lost-write-looks-like-failed-read]]). `rerender` rides out as information, never as the # verdict. - return {"database": database, "view_id": view_id, "rerender": bool(rerender)} + if (kind == "view_upsert" and + (not after or str(after[0]).strip().lower() + != str(session.uname).strip().lower())): + raise err(409, "view_not_personal", f"View {view_id}: the personal draft was not saved.") + return {"database": database, "view_id": view_id, "rerender": bool(rerender), + "draft": "personal", "shared": False} def _application_upsert(session, args): @@ -674,7 +1881,435 @@ def _application_upsert(session, args): routes_assets._application_error(exc) -def _tool_context(session: Session) -> external_tools.ToolContext: +def _bucket_revision(st, key, fallback): + try: + revision = st.revision(key) + if isinstance(revision, dict): + return copy.deepcopy(revision) + except Exception: + pass + return {"rev": None, "token": _json_digest(fallback)} + + +def _database_value_plan(session, database, record_id, values, fields): + """Apply the grid's field/value vocabulary without calling its event side effects.""" + from core import grid_events, user_tables + import aios_grid + + if not isinstance(values, dict) or not values: + raise err(400, "tool_arguments_invalid", "Record values must be a non-empty object.") + field_by_key = {str(field.get("key")): field for field in fields if isinstance(field, dict)} + unknown = sorted(str(key) for key in values if str(key) not in field_by_key) + if unknown: + raise err(403, "field_unavailable", + "Every changed field must be readable and editable in this database.") + ctx = _view_context(session, database, {"pid": record_id}) + planned = {} + for key, raw in values.items(): + key = str(key) + definition = field_by_key[key] + if key in (ctx.hidden_keys or frozenset()) or not grid_events._may_edit_field_value( + ctx, key, definition): + raise err(403, "field_unavailable", + "Every changed field must be readable and editable in this database.") + if user_tables.is_computed_cell(definition) or definition.get("type") == "automation": + raise err(403, "computed_field", "A computed or automation field is read only.") + why = user_tables.cell_type_refusal(definition, raw) + if why: + raise err(400, "bad_value", why) + if definition.get("type") == "link": + bag = definition.get("link") if isinstance(definition.get("link"), dict) else {} + if bag.get("on") or bag.get("inverse"): + raise err(403, "computed_field", "A derived link field is read only.") + target = user_tables.get(str(bag.get("table") or ""), st=session.runtime) or {} + available = set((target.get("rows") or {}).keys()) + raw_ids = raw if isinstance(raw, (list, tuple, set)) else str(raw or "").split(",") + selected = [] + for item in raw_ids: + candidate = str(item).strip() + if not candidate or candidate in selected: + continue + if candidate not in available or len(selected) >= user_tables.LINK_MAX_IDS: + raise err(400, "bad_value", "A linked record is unavailable.") + selected.append(candidate) + if bag.get("single"): + break + planned[key] = ",".join(selected) + continue + if isinstance(definition.get("profile"), dict): + handle, ok = user_tables.normalize_profile(raw, definition["profile"].get("source")) + if not ok: + raise err(400, "bad_value", "That value is not a valid profile handle.") + planned[key] = handle + continue + if definition.get("type") == "json": + text = raw if isinstance(raw, str) else json.dumps(raw, separators=(",", ":")) + if text.strip(): + try: + json.loads(text) + except (ValueError, TypeError) as exc: + raise err(400, "bad_value", "A JSON field requires a valid JSON document.") from exc + planned[key] = text + continue + clean = str(raw)[:10000] + if isinstance(raw, str) and clean != raw: + raise err(400, "bad_value", "A field value exceeds the supported length.") + if definition.get("type") in ("select", "multiselect") and clean: + options = aios_grid.merge_choice_options(definition.get("options")) + canonical = {value.casefold(): value for value in options} + parts = [clean] if definition.get("type") == "select" else clean.split(",") + selected = [] + for part in parts: + candidate = aios_grid._clean_options([part]) + if len(candidate) != 1: + raise err(400, "bad_value", "A choice value is invalid.") + value = canonical.get(candidate[0].casefold(), candidate[0]) + if value not in selected: + selected.append(value) + clean = selected[0] if definition.get("type") == "select" else ",".join(selected) + planned[key] = clean + return planned + + +def _plan_database_write(session, args): + import routes_tables + from core import user_tables + + action = args.get("action") + database = str(args.get("database") or "").strip() + if action not in {"record_create", "record_update", "record_delete", + "field_create", "field_update", "field_delete"} or not database: + raise err(400, "tool_arguments_invalid", "Name a database and a published CRUD action.") + _assert_database_scope(session, database) + _assert_write_scope(session, "database_object") + routes_tables._managed_or_refuse(session, database, mutation=True) + bucket_before = session.runtime.get(user_tables.STORE_KEY) + if not isinstance(bucket_before, dict): + raise err(503, "store_unavailable", "The database store is unavailable. Nothing was saved.") + table = copy.deepcopy(bucket_before.get(database) or {}) + if not table or not user_tables.is_user_table(database, st=session.runtime): + raise err(403, "connected_source_read_only", + "Connected and Odoo-backed database records are read only.") + revision = _bucket_revision(session.runtime, user_tables.STORE_KEY, bucket_before) + if type(revision.get("rev")) is not int: + raise err(503, "confirmation_revision_unavailable", + "This deployment cannot revision-guard a database change.") + warnings = [] + bucket_after = copy.deepcopy(bucket_before) + + if action.startswith("record_"): + routes_tables._records_or_refuse(session, database) + g = routes_tables.ut_write_ctx(session, database) + rows = table.get("rows") or {} + if action == "record_create": + values = _database_value_plan(session, database, None, args.get("values"), g["fields"]) + record_id = str(max((int(key) for key in rows if str(key).isdigit()), default=0) + 1) + before, after = None, values + else: + record_id = str(args.get("record_id") or "").strip() + if not record_id.isdigit() or int(record_id) not in g["pids"]: + raise err(403, "record_unavailable", "That record is not available to this account.") + before = copy.deepcopy(rows.get(record_id)) + if before is None: + raise err(403, "record_unavailable", "That record is not available to this account.") + if action == "record_update": + values = _database_value_plan( + session, database, int(record_id), args.get("values"), g["fields"]) + after = {**before, **values} + for key, value in values.items(): + if isinstance(next((field for field in g["fields"] + if field.get("key") == key), {}).get("profile"), dict) and not value: + for field in table.get("fields") or (): + if (field.get("key") in user_tables.PROFILE_PRESET_KEYS + and isinstance(field.get("automation"), dict)): + after[field["key"]] = "" + else: + after = None + target = bucket_after[database] + if action == "record_delete": + (target.get("rows") or {}).pop(record_id, None) + else: + target.setdefault("rows", {})[record_id] = copy.deepcopy(after) + # This is part of the UI row writer's durable result, not an optional callback. + # Include newly encountered select values in the preview and the one guarded commit. + user_tables._hydrate_choice_options(target.get("fields") or [], [after]) + changed, truncated = _diff_documents({user_tables.STORE_KEY: { + "before": bucket_before, "after": bucket_after}}) + if truncated: + warnings.append("The preview diff reached its display cap; split this change.") + return {"diff": changed, "affected": {"ids": [record_id], "count": 1}, + "warnings": warnings, "revision": revision, + "bucket_before_digest": _json_digest(bucket_before), + "bucket_after": bucket_after, + "planned": {"database": database, "action": action, "record_id": record_id}} + + field_key = str(args.get("field_key") or "").strip() + visible = routes_tables.ut_write_ctx(session, database)["fields"] + recurrence_validator = lambda raw: __import__("routes_grid").govern_date_recurrence( + session, database, visible, raw) + if action == "field_create": + routes_tables._field_or_refuse(session, database) + raw = args.get("field") + if not isinstance(raw, dict): + raise err(400, "tool_arguments_invalid", "field must be an object.") + have = list(table.get("fields") or []) + field = user_tables._clean_field( + raw, recurrence_validator=recurrence_validator, + valid_keys={str(item.get("key")) for item in have if item.get("key")}) + if (not field or any(item.get("key") == field.get("key") for item in have) + or len(have) >= user_tables.MAX_FIELDS + or not user_tables.dynamic_link_filter_valid(field, have) + or not user_tables.flow_bound(field.get("automation"), session.runtime)): + raise err(400, "field_refused", "The field does not pass the database's schema rules.") + field_key, before, after = field["key"], None, field + else: + if not field_key: + raise err(400, "tool_arguments_invalid", "Name the field to change.") + routes_tables._field_or_refuse(session, database, field_key) + before = next((copy.deepcopy(field) for field in table.get("fields") or () + if field.get("key") == field_key), None) + if before is None: + raise err(403, "field_unavailable", "That field is not available to this account.") + if action == "field_update": + raw = args.get("field") + if not isinstance(raw, dict) or "renames" in raw: + raise err(400, "field_refused", + "External schema updates do not combine choice-value migrations.") + merged = {**raw, "key": field_key} + after = user_tables._clean_field( + merged, before, recurrence_validator=recurrence_validator, + valid_keys=({str(item.get("key")) for item in table.get("fields") or () + if item.get("key") != field_key} + if "formula" in raw else None)) + if (not after or not user_tables.dynamic_link_filter_valid( + after, table.get("fields") or ())): + raise err(400, "field_refused", "The field does not pass the database's schema rules.") + else: + if (len(table.get("fields") or ()) <= 1 or before.get("deletionLocked") is True + or user_tables.delete_field_refusal( + database, field_key, session.uname, session.admin, session.runtime, + field=before, grant_topic=database) is not None): + raise err(403, "field_refused", "That field cannot be removed.") + after = None + # Build the exact schema document through the core schema mechanics on an isolated runtime. + # This includes reciprocal-link cleanup/creation while keeping preview free of relation + # refreshes, audit calls, automation events and every other out-of-store side effect. + preview = _PreviewRuntime(session.runtime) + preview.update(user_tables.STORE_KEY, lambda _cur: copy.deepcopy(bucket_before)) + if action == "field_create": + stored = user_tables.add_field( + database, after, st=preview, recurrence_validator=recurrence_validator) + if not stored: + raise err(400, "field_refused", "The field does not pass the database's schema rules.") + synced = user_tables.sync_reciprocal_link(database, field_key, st=preview) + if synced.get("refused"): + warnings.append(str(synced.get("reason") or "A reciprocal field was not created.")) + elif action == "field_update": + stored = user_tables.patch_field( + database, field_key, after, st=preview, recurrence_validator=recurrence_validator) + if not stored: + raise err(400, "field_refused", "The field does not pass the database's schema rules.") + synced = user_tables.sync_reciprocal_link(database, field_key, st=preview) + if synced.get("refused"): + warnings.append(str(synced.get("reason") or "A reciprocal field was not created.")) + elif not user_tables.delete_field(database, field_key, st=preview): + raise err(403, "field_refused", "That field cannot be removed.") + bucket_after = preview.get(user_tables.STORE_KEY) + changed, truncated = _diff_documents({user_tables.STORE_KEY: { + "before": bucket_before, "after": bucket_after}}) + if truncated: + warnings.append("The preview diff reached its display cap; split this change.") + affected_ids = [field_key] + for item in changed: + for side in (item.get("before"), item.get("after")): + candidate = side.get("key") if isinstance(side, dict) else None + if candidate and str(candidate) not in affected_ids: + affected_ids.append(str(candidate)) + return {"diff": changed, + "affected": {"ids": affected_ids, "count": len(affected_ids)}, + "warnings": warnings, "revision": revision, + "bucket_before_digest": _json_digest(bucket_before), + "bucket_after": bucket_after, + "planned": {"database": database, "action": action, "field_key": field_key}} + + +def _execute_database_object(session, args, *, plan=None): + from core import user_tables, view_audit + + action = args.get("action") + database = str(args.get("database") or "").strip() + if action == "list": + return list_databases(session) + if action == "describe": + return database_schema(database, session) + if action == "query": + return _query_database(session, database, args.get("query") or {}) + plan = plan or _plan_database_write(session, args) + expected_rev = plan.get("revision", {}).get("rev") + expected_digest = plan.get("bucket_before_digest") + replacement = copy.deepcopy(plan.get("bucket_after")) + if type(expected_rev) is not int or not isinstance(replacement, dict): + raise err(503, "confirmation_revision_unavailable", + "This deployment cannot revision-guard a database change.") + + def apply_exact(current): + if _json_digest(current) != expected_digest: + raise view_audit.ViewRevisionStale( + rev_sent=expected_rev, rev_current=expected_rev + 1, + message="The database changed after preview.") + return copy.deepcopy(replacement) + + try: + # One customer bucket, one guarded read-modify-write. The expected revision is checked + # inside the PG lock where available; the closure's digest check also protects a backend + # that can only provide the runtime's documented guarded fallback. + session.runtime.update( + user_tables.STORE_KEY, apply_exact, flush="sync", expect_rev=expected_rev) + except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc: + raise err(409, "confirmation_stale", + "The database changed after preview. Preview the change again.") from exc + return {"database": database, **copy.deepcopy(plan.get("planned") or {}), + "affected": copy.deepcopy(plan.get("affected") or {})} + + +def _sheet_compat_contract(): + """Load C5's neighboring manifest/dispatcher without defining a second inventory here.""" + try: + module = importlib.import_module("core.sheet_compat") + except (ImportError, ModuleNotFoundError): + raise sheets.SheetRefusal( + "tool_capability_unsupported", + "This deployment has not published the Sheet compatibility manifest.") + manifest = None + for name in ("capability_manifest", "get_capability_manifest", "CAPABILITY_MANIFEST", + "CAPABILITIES"): + candidate = getattr(module, name, None) + if callable(candidate): + try: + candidate = candidate() + except TypeError: + continue + if isinstance(candidate, (dict, list, tuple)): + manifest = copy.deepcopy(candidate) + break + if manifest is None: + raise sheets.SheetRefusal( + "tool_capability_unsupported", + "This deployment has not published a readable Sheet compatibility manifest.") + return module, manifest + + +def _manifest_operation(manifest, object_name, action): + """Return an explicitly supported C5 entry; absence and ambiguity both fail closed.""" + object_name, action = str(object_name).casefold(), str(action).casefold() + wanted = {f"{object_name}.{action}", f"{object_name}s.{action}", + f"{object_name}/{action}"} + matches = [] + + def walk(node, path=()): + if isinstance(node, dict): + explicit_name = node.get("operation") or node.get("name") or node.get("id") + if explicit_name is not None: + full = str(explicit_name).casefold() + if full in wanted or (object_name in full and action in full): + matches.append(node) + for key, value in node.items(): + key_text = str(key).casefold() + full_path = ".".join((*path, key_text)) + if (key_text in wanted or full_path in wanted + or (object_name in full_path and action in full_path)): + if isinstance(value, dict): + matches.append(value) + elif isinstance(value, bool): + matches.append({"supported": value}) + if key not in {"examples", "fixtures", "notes"}: + walk(value, (*path, key_text)) + elif isinstance(node, (list, tuple)): + for item in node: + walk(item, path) + + walk(manifest) + for entry in matches: + if entry.get("supported") is True or str(entry.get("status") or "").casefold() in { + "supported", "implemented", "available"}: + return entry + raise sheets.SheetRefusal( + "tool_capability_unsupported", + f"The C5 capability manifest does not support {object_name}.{action}.") + + +def _invoke_compat(dispatcher, *, session, object_name, action, arguments, operations=None): + supplied = { + "session": session, "runtime": session.runtime, "actor": session.uname, + "username": session.uname, "object": object_name, "object_name": object_name, + "action": action, "operation": f"{object_name}.{action}" if object_name else None, + "arguments": copy.deepcopy(arguments), "operations": copy.deepcopy(operations), + } + try: + signature = inspect.signature(dispatcher) + if any(param.kind == inspect.Parameter.VAR_KEYWORD + for param in signature.parameters.values()): + return dispatcher(**supplied) + kwargs = {key: value for key, value in supplied.items() + if key in signature.parameters} + if not kwargs and len(signature.parameters) == 1: + return dispatcher(copy.deepcopy(arguments if operations is None else operations)) + return dispatcher(**kwargs) + except sheets.SheetRefusal: + raise + except (TypeError, ValueError, KeyError, AttributeError) as exc: + raise sheets.SheetRefusal( + "tool_capability_unsupported", + "The published Sheet compatibility dispatcher does not implement this operation.") from exc + + +def _sheet_object(session, args): + object_name = str(args.get("object") or "").strip().casefold() + action = str(args.get("action") or "").strip() + module, manifest = _sheet_compat_contract() + _manifest_operation(manifest, object_name, action) + dispatcher = next((getattr(module, name, None) for name in ( + "dispatch_object_operation", "dispatch_operation", "execute_operation", "dispatch") + if callable(getattr(module, name, None))), None) + if dispatcher is None: + raise sheets.SheetRefusal( + "tool_capability_unsupported", + "The published Sheet capability has no object-operation dispatcher.") + return _invoke_compat( + dispatcher, session=session, object_name=object_name, action=action, + arguments={key: copy.deepcopy(value) for key, value in args.items() if key != "object"}) + + +def _validated_batch(session, args): + operations = args.get("operations") + if not isinstance(operations, list) or not operations: + raise err(400, "tool_arguments_invalid", "A validated batch needs at least one operation.") + module, manifest = _sheet_compat_contract() + normalised = [] + for item in operations: + if not isinstance(item, dict) or set(item) != {"name", "arguments"}: + raise err(400, "tool_arguments_invalid", "Every batch item needs name and arguments.") + name, arguments = item.get("name"), item.get("arguments") + if name not in external_tools._SHEET_OBJECT_ACTIONS or not isinstance(arguments, dict): + raise sheets.SheetRefusal( + "tool_capability_unsupported", "Validated batches contain only C5 object tools.") + object_name = name.removesuffix("_object") + action = str(arguments.get("action") or "") + _manifest_operation(manifest, object_name, action) + normalised.append({"name": name, "arguments": copy.deepcopy(arguments)}) + dispatcher = next((getattr(module, name, None) for name in ( + "dispatch_validated_batch", "execute_validated_batch", "dispatch_batch") + if callable(getattr(module, name, None))), None) + if dispatcher is None: + raise sheets.SheetRefusal( + "tool_capability_unsupported", + "The C5 manifest does not publish an atomic validated-batch dispatcher.") + return _invoke_compat( + dispatcher, session=session, object_name="", action="", arguments=args, + operations=normalised) + + +def _tool_context(session: Session, *, preview=False) -> external_tools.ToolContext: # Import within the API layer. Core receives callbacks, never an upward dependency. import routes_sheet import formula_runtime @@ -714,10 +2349,16 @@ def _tool_context(session: Session) -> external_tools.ToolContext: except Exception: pass - label = external_access.label_for(session.runtime, session.claims["external_key_id"]) + if session.claims.get("external_auth_type") == "oauth": + label = external_oauth.label_for( + session.runtime, session.claims["external_credential_id"]) + attribution_kind = "OAuth app" + else: + label = external_access.label_for(session.runtime, session.claims["external_key_id"]) + attribution_kind = "key" maker = session.user.get("name") or session.uname - actor_name = f"{maker} via key {label}" - if _CREDENTIAL_PREFIX in actor_name: + actor_name = f"{maker} via {attribution_kind} {label}" + if _contains_credential(actor_name): raise sheets.SheetRefusal("credential_in_attribution", "Maker names and key labels must not contain credential values.") return external_tools.ToolContext( session=session, actor_name=actor_name, @@ -728,27 +2369,302 @@ def _tool_context(session: Session) -> external_tools.ToolContext: cache_binding=cache_binding, list_databases=lambda: list_databases(session), describe_database=lambda database: database_schema(database, session), + query_database=lambda database, payload: _query_database(session, database, payload), view_event=lambda kind, args: _view_event(session, kind, args), + view_share_preview=lambda args: _view_share_preview(session, args), app_upsert=lambda args: _application_upsert(session, args), # Reuse the UI's atomic NameConfirmedDelete wrapper as well as the registry delete. app_delete=lambda args: routes_assets.delete_application( args["app_id"], {"confirmName": args["confirmName"]}, session), + database_object=lambda args: (_plan_database_write(session, args) + if preview and external_tools.is_write( + "database_object", args) + else _execute_database_object(session, args)), + sheet_object=lambda args: _sheet_object(session, args), + validated_batch=lambda args: _validated_batch(session, args), + confirm_change=lambda args: _confirm_change(session, args), ) +def _strong_confirmation_required(name, args): + if name == "database_object": + return args.get("action") in {"record_delete", "field_create", "field_update", "field_delete"} + if name in {"view_delete", "app_delete"}: + return True + if name == "sheet_write_cells": + return any(isinstance(cell, dict) and cell.get("kind") == "empty" + for cell in (args.get("cells") or {}).values()) + if name == "view_object": + return args.get("action") == "delete" + if name == "sheet_structure": + return int(((args.get("op") or {}).get("delta") or 0)) < 0 + if name == "worksheet_object": + return args.get("action") == "delete" + if name == "range_object": + return args.get("action") == "clear" + if name == "validated_batch": + return any(_strong_confirmation_required( + item.get("name"), item.get("arguments") or {}) + for item in args.get("operations") or () if isinstance(item, dict)) + return False + + +def _affected_for(name, args, diff, result=None): + values = [] + for key in ("database", "record_id", "field_key", "view_id", "app_id", + "workbook_id", "worksheet", "tab", "range", "addr"): + value = args.get(key) + if value is not None and str(value) not in values: + values.append(str(value)) + if isinstance(result, dict): + for key in ("rid", "pid", "id", "view_id", "app_id", "chart_id"): + value = result.get(key) + if value is not None and str(value) not in values: + values.append(str(value)) + return {"ids": values[:100], "count": max(len(values), len(diff))} + + +def _preview_external_write(session, name, arguments, *, issue_token=True, execution=None): + from core import write_execution + if not external_tools.is_write(name, arguments): + raise err(400, "confirmation_not_write", "Only a write operation can be previewed.") + _assert_write_scope(session, name) + normalised = json.loads(_canonical_json(arguments).decode("utf-8")) + for database in _databases_in_arguments(normalised): + _assert_database_scope(session, database) + + preview_runtime = _PreviewRuntime(session.runtime) + preview_session = Session( + tenant=session.tenant, user=copy.deepcopy(session.user), + claims=copy.deepcopy(session.claims), runtime=preview_runtime) + execution = execution or {'seed': uuid.uuid4().hex, 'timestamp': time.time()} + with write_execution.replay(execution): + result = external_tools.dispatch(_tool_context(preview_session, preview=True), name, normalised) + if isinstance(result, dict) and result.get("refused"): + raise err(409, "write_partial_refused", + "The writer refused part of this change; nothing was previewed.") + + plan = result if name == "database_object" else None + if plan is not None: + diff = copy.deepcopy(plan.get("diff") or []) + warnings = list(plan.get("warnings") or []) + affected = copy.deepcopy(plan.get("affected") or {}) + current_revision = copy.deepcopy(plan.get("revision") or {}) + else: + documents = preview_runtime.changed() + diff, truncated = _diff_documents(documents) + warnings = (["The preview diff reached its display cap; split this change."] + if truncated else []) + affected = _affected_for(name, normalised, diff, result) + current_revision = { + key: revision for key, revision in preview_runtime.base_revisions().items() + if key in documents + } + if not diff: + raise err(409, "write_not_changed", "The requested write would not change anything.") + if any("display cap" in warning for warning in warnings): + raise err(413, "confirmation_too_large", + "The complete diff does not fit in one confirmation. Split the change.") + + diff_digest = _json_digest(diff) + revision_digest = _json_digest(current_revision) + expires_at = int(time.time()) + _CONFIRMATION_TTL_SECONDS + payload = { + "v": 1, "tenant": session.tenant, "actor": session.uname, + "credential": _credential_binding(session), + "authentication": session.claims.get("external_auth_type", "api_key"), + "tool": name, "arguments": normalised, + "arguments_digest": _json_digest(normalised), + "revision_digest": revision_digest, "diff_digest": diff_digest, + "expiry": expires_at, "nonce": uuid.uuid4().hex, + "strong": _strong_confirmation_required(name, normalised), + "affected_count": int(affected.get("count") or 0), + "execution": execution, + } + response = { + "preview": True, "mutated": False, "tool": name, + "diff": diff, "diff_digest": diff_digest, + "affected": affected, "warnings": warnings, + "current_revision": current_revision, + "expires_at": expires_at, "requires_confirmation": True, + "strong_confirmation_required": payload["strong"], + } + if payload["strong"]: + response["confirmation_phrase"] = _CONFIRMATION_PHRASE + if issue_token: + response["confirmation_token"] = _confirmation_token(payload) + response["_confirmation"] = payload + response["_plan"] = plan + return response + + +def _confirmation_claim(session, payload): + nonce = str(payload.get("nonce") or "") + if not nonce: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + nonce_key = hashlib.sha256(nonce.encode("utf-8")).hexdigest() + + def claim(raw): + doc = raw if isinstance(raw, dict) else {} + claims = doc.get("claims") if isinstance(doc.get("claims"), dict) else {} + now = int(time.time()) + claims = {key: value for key, value in claims.items() + if isinstance(value, dict) and int(value.get("expiry") or 0) >= now - 3600} + if nonce_key in claims: + raise err(409, "confirmation_replayed", + "This confirmation token has already been used.") + claims[nonce_key] = { + "status": "claimed", "expiry": int(payload["expiry"]), + "tool": str(payload["tool"]), "actor_digest": _json_digest(payload["actor"]), + "diff_digest": str(payload["diff_digest"]), + } + doc["claims"] = claims + return doc + + session.runtime.update(_CONFIRMATION_BUCKET, claim, flush="sync") + return nonce_key + + +def _confirmation_already_used(session, payload): + nonce = str(payload.get("nonce") or "") + if not nonce: + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + nonce_key = hashlib.sha256(nonce.encode("utf-8")).hexdigest() + doc = session.runtime.get(_CONFIRMATION_BUCKET) + claims = doc.get("claims") if isinstance(doc, dict) and isinstance(doc.get("claims"), dict) else {} + if nonce_key in claims: + raise err(409, "confirmation_replayed", "This confirmation token has already been used.") + + +def _confirmation_status(session, nonce_key, status): + def mark(raw): + doc = raw if isinstance(raw, dict) else {} + claims = doc.get("claims") if isinstance(doc.get("claims"), dict) else {} + item = claims.get(nonce_key) + if isinstance(item, dict): + claims[nonce_key] = {**item, "status": status} + doc["claims"] = claims + return doc + try: + session.runtime.update(_CONFIRMATION_BUCKET, mark, flush="sync") + except Exception: + pass + + +def _confirm_change(session, args): + from core import view_audit, write_execution + + payload = _read_confirmation_token(args.get("confirmation_token")) + now = int(time.time()) + if int(payload.get("expiry") or 0) <= now: + raise err(409, "confirmation_expired", + "This confirmation token expired. Preview the change again.") + bindings = { + "tenant": session.tenant, "actor": session.uname, + "credential": _credential_binding(session), + "authentication": session.claims.get("external_auth_type", "api_key"), + } + if any(payload.get(key) != value for key, value in bindings.items()): + raise err(403, "confirmation_principal_changed", + "This confirmation belongs to another principal or credential.") + if payload.get("strong") and args.get("confirmation_phrase") != _CONFIRMATION_PHRASE: + raise err(400, "confirmation_phrase_required", + "Enter the exact stronger confirmation phrase shown in the preview.") + _confirmation_already_used(session, payload) + + # Freshly resolve the account, Analyst grant, credential revocation/label, credential scope, + # database walls and writer semantics before claiming the nonce or touching customer state. + fresh_user = external_access.resolve_active_user(session.uname, session.tenant) + fresh_session = Session(session.tenant, fresh_user, copy.deepcopy(session.claims), session.runtime) + require_external_analyst(fresh_session) + _tool_context(fresh_session) # credential label lookup is the live revocation check + tool, arguments = payload.get("tool"), payload.get("arguments") + if not isinstance(tool, str) or tool == "confirm_change" or not isinstance(arguments, dict): + raise err(400, "confirmation_token_invalid", "The confirmation token is invalid.") + execution = payload.get('execution') + if (not isinstance(execution, dict) or not isinstance(execution.get('seed'), str) + or not execution['seed'] or type(execution.get('timestamp')) not in (int, float)): + raise err(409, 'confirmation_stale', + 'This preview predates the current writer. Preview the change again.') + recomputed = _preview_external_write( + fresh_session, tool, arguments, issue_token=False, execution=execution) + current = recomputed["_confirmation"] + if (payload.get("arguments_digest") != current.get("arguments_digest") + or payload.get("revision_digest") != current.get("revision_digest") + or payload.get("diff_digest") != current.get("diff_digest")): + raise err(409, "confirmation_stale", + "The data, permissions, or resulting diff changed. Preview the change again.") + + nonce_key = _confirmation_claim(fresh_session, payload) + try: + if tool == "database_object": + result = _execute_database_object( + fresh_session, arguments, plan=recomputed.get("_plan")) + else: + guarded_session = Session( + fresh_session.tenant, fresh_session.user, fresh_session.claims, + _ConfirmationRuntime( + fresh_session.runtime, recomputed.get("current_revision"))) + with write_execution.replay(execution): + result = external_tools.dispatch(_tool_context(guarded_session), tool, arguments) + if isinstance(result, dict) and result.get("refused"): + raise err(409, "write_partial_refused", + "The writer refused part of the confirmed change.") + except (view_audit.ViewRevisionStale, view_audit.RevisionUnverifiable) as exc: + _confirmation_status(fresh_session, nonce_key, "failed") + raise err(409, "confirmation_stale", + "The data changed while confirmation was committing. Preview it again.") from exc + except Exception: + _confirmation_status(fresh_session, nonce_key, "failed") + raise + _confirmation_status(fresh_session, nonce_key, "committed") + before_revision = copy.deepcopy(recomputed.get("current_revision") or {}) + if tool == "database_object": + from core import user_tables + after_revision = _bucket_revision( + fresh_session.runtime, user_tables.STORE_KEY, + fresh_session.runtime.get(user_tables.STORE_KEY)) + else: + after_revision = {} + for key in before_revision if isinstance(before_revision, dict) else (): + try: + after_revision[key] = copy.deepcopy(fresh_session.runtime.revision(key)) + except Exception: + after_revision[key] = None + after_revision_digest = _json_digest(after_revision) + receipt = audit.external_write_receipt( + fresh_session.tenant, fresh_session.uname, tool=tool, + auth_type=payload.get("authentication"), + affected_count=payload.get("affected_count"), + diff_digest=payload.get("diff_digest"), + revision_before=payload.get("revision_digest"), revision_after=after_revision_digest, + confirmation_id=nonce_key) + return { + "confirmed": True, "applied": True, "tool": tool, + "affected": copy.deepcopy(recomputed.get("affected") or {}), + "revision_before": before_revision, + "revision_after": after_revision, "audit_receipt": receipt, + } + + def _tool_refusal(name, code, message, status=400, **extra): # Never echo arbitrary method/tool names or raw exception text across the bearer seam. tool_name = name if isinstance(name, str) and name in external_tools.TOOLS else "tools/call" sentence = f"{tool_name}: {_markdown_inline(message)}" - if _CREDENTIAL_PREFIX in sentence: + if _contains_credential(sentence): sentence = f"{tool_name}: The result contained a credential value and was withheld." return {"ok": False, "error": {"tool": tool_name, "code": code, "message": sentence, "status": status, **extra}} def _mcp_content(rid, out): - encoded = json.dumps(out, default=str, ensure_ascii=True, allow_nan=False) - if _CREDENTIAL_PREFIX in encoded: + try: + encoded = json.dumps(out, default=str, ensure_ascii=True, allow_nan=False) + except (TypeError, ValueError, OverflowError): + out = _tool_refusal(None, "tool_output_invalid", + "The result could not be represented safely.", 422) + encoded = json.dumps(out) + if _contains_credential(encoded): out = _tool_refusal(None, "credential_in_output", "The result contained a credential value and was withheld.") encoded = json.dumps(out) return {"jsonrpc": "2.0", "id": rid, "result": { @@ -763,7 +2679,7 @@ def _handle_mcp(req, session: Session): if not isinstance(req, dict): return protocol_error(None, -32600, "An MCP request must be a JSON-RPC object.") rid, method = req.get("id"), req.get("method") - if (rid is not None and (type(rid) not in (str, int) or _CREDENTIAL_PREFIX in str(rid))): + if (rid is not None and (type(rid) not in (str, int) or _contains_credential(rid))): return protocol_error(None, -32600, "The request id must be a number or a safe string.") if rid is None: # Notifications never dispatch writes and never return a JSON-RPC body. @@ -780,7 +2696,7 @@ def _handle_mcp(req, session: Session): require_external_analyst(session) if method == "initialize": protocol = params.get("protocolVersion") or "2025-06-18" - if not isinstance(protocol, str) or _CREDENTIAL_PREFIX in protocol: + if not isinstance(protocol, str) or _contains_credential(protocol): return protocol_error(rid, -32602, "The protocol version must be a safe string.") return {"jsonrpc": "2.0", "id": rid, "result": { "protocolVersion": protocol, "capabilities": {"tools": {}}, @@ -793,11 +2709,18 @@ def _handle_mcp(req, session: Session): for key, tool in external_tools.TOOLS.items()]}} if method != "tools/call": return protocol_error(rid, -32601, "The requested MCP method was not found.") - if isinstance(name, str) and name in _WRITE_TOOLS: - _assert_write_scope(session, name) - for database in _databases_in_arguments(params.get("arguments", {})): + arguments = params.get("arguments", {}) + for database in _databases_in_arguments(arguments): _assert_database_scope(session, database) - data = external_tools.dispatch(_tool_context(session), name, params.get("arguments", {})) + if name == "confirm_change": + data = external_tools.dispatch(_tool_context(session), name, arguments) + elif external_tools.is_write(name, arguments): + _assert_write_scope(session, name) + data = _preview_external_write(session, name, arguments) + data.pop("_confirmation", None) + data.pop("_plan", None) + else: + data = external_tools.dispatch(_tool_context(session), name, arguments) if isinstance(data, dict) and data.get("refused"): first = data["refused"][0] out = _tool_refusal(name, first["code"], first["sentence"]) @@ -847,6 +2770,8 @@ _WRITE_TOOLS = frozenset({ "sheet_add_rule", "sheet_set_chart", "sheet_structure", "sheet_save_template", "view_upsert", "view_delete", "app_upsert", "app_delete", + "database_object", "view_object", "workbook_object", "worksheet_object", + "range_object", "calculation_object", "validated_batch", }) @@ -860,3 +2785,37 @@ def _assert_write_allow_list() -> None: _assert_write_allow_list() + + +# RFC 8414 and RFC 9728 insert `.well-known` before a path-bearing issuer/resource. Keep the +# path-local aliases above for compatibility, while the router mounted by `main.py` also serves +# the standards-derived locations followed by generic OAuth and MCP clients. The auxiliary +# router's already-built routes are appended directly so the established external router prefix +# remains unchanged for every existing caller and invariant. +_discovery_router = APIRouter(tags=["external"]) + + +@_discovery_router.get("/.well-known/oauth-authorization-server/api/v1/external") +def oauth_server_metadata_rfc(request: Request): + return oauth_server_metadata(request) + + +@_discovery_router.get("/.well-known/oauth-protected-resource/api/v1/external/mcp") +def oauth_resource_metadata_rfc(request: Request): + return oauth_resource_metadata(request) + + +# The PUBLIC skill.md at the site root, like Monid's `monid.ai/SKILL.md`: an agent told +# "set up /skill.md" reads it with no session. It is the session-free document, so it +# carries no tenant, database or field name; `/api/v1/external/skill.md` keeps the per-user one. +@_discovery_router.get("/skill.md") +@_discovery_router.get("/SKILL.md") +def public_skill(request: Request): + return Response( + content=_portable_skill_document(None, str(request.base_url)), + media_type="text/markdown; charset=utf-8", + headers={"Cache-Control": "public, max-age=300"}, + ) + + +router.routes.extend(_discovery_router.routes)