runloopable / platform /core /external_oauth.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
816fa8a verified
Raw History Blame Contribute Delete
38.5 kB
"""Hash-only OAuth 2.1-style authorization for the existing remote MCP resource.
The authorization endpoint is the only browser-session step. Code exchange, refresh, bearer
verification, and disconnect resolve from opaque tokens and fresh tenant state without a cookie.
Public clients use PKCE S256 and have no shared client secret to leak or impersonate a user.
"""
from __future__ import annotations
import base64
from dataclasses import dataclass
import hashlib
import hmac
import secrets
import time
from urllib.parse import urlsplit, urlunsplit
from core import external_access, perm_scope, perms, registry, shares, user_tables, users
BUCKET = "external_oauth"
ALGORITHM = "sha256-salt-v1"
CODE_TTL_SECONDS = 5 * 60
ACCESS_TTL_SECONDS = 60 * 60
REFRESH_TTL_SECONDS = 30 * 24 * 60 * 60
MAX_REFRESH_ROTATIONS = 256
MAX_REDIRECT_URIS = 10
SCOPES = ("mcp:read", "mcp:write", "offline_access")
AUTH_ERROR = external_access.AUTH_ERROR
_STAMP_EVERY = 900.0
_DUMMY_SALT = bytes(32)
_DUMMY_HASH = hashlib.sha256(_DUMMY_SALT + b"invalid").hexdigest()
_UNSET = object()
class ExternalOAuthError(external_access.ExternalAccessError):
"""Stable OAuth refusal; HTTP vocabulary belongs to the API route."""
class ExternalOAuthAuthError(ExternalOAuthError):
"""Uniform bearer refusal with no tenant, client, or grant oracle."""
@dataclass(frozen=True)
class VerifiedOAuth:
tenant: str
grant_id: str
client_id: str
user: dict
runtime: object
access: str
databases: object
scopes: tuple[str, ...]
resource: str
@dataclass(frozen=True)
class DisconnectedOAuth:
"""Safe attribution plus public metadata for one token-authenticated disconnect."""
tenant: str
username: str
connection: dict
def _now(now=None) -> float:
return time.time() if now is None else float(now)
def _iso(epoch: float | None) -> str | None:
if epoch is None:
return None
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(epoch))
def _digest(salt: bytes, secret: str) -> str:
return hashlib.sha256(salt + secret.encode("utf-8")).hexdigest()
def _state_digest(state: str) -> str:
return hashlib.sha256(state.encode("utf-8")).hexdigest()
def _pkce_challenge(verifier: str) -> str:
return base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
def _book(st, *, fresh=True) -> dict:
try:
value = st.get(BUCKET, fresh=fresh)
except Exception as exc:
raise ExternalOAuthError("oauth_unavailable") from exc
if value is None:
return {"clients": {}, "codes": {}, "states": {}, "grants": {}}
if not isinstance(value, dict):
raise ExternalOAuthError("oauth_unavailable")
out = {}
for key in ("clients", "codes", "states", "grants"):
child = value.get(key, {})
if not isinstance(child, dict):
raise ExternalOAuthError("oauth_unavailable")
out[key] = child
return out
def _normalise_redirect_uris(value) -> tuple[str, ...]:
if not isinstance(value, (list, tuple)) or not 1 <= len(value) <= MAX_REDIRECT_URIS:
raise ExternalOAuthError("oauth_redirect_uri_invalid")
clean = []
for raw in value:
if not isinstance(raw, str) or not raw.strip() or len(raw.strip()) > 1000:
raise ExternalOAuthError("oauth_redirect_uri_invalid")
uri = raw.strip()
parsed = urlsplit(uri)
loopback = parsed.scheme == "http" and (parsed.hostname or "").lower() in {
"localhost", "127.0.0.1", "::1",
}
if (parsed.fragment or parsed.username or parsed.password or not parsed.netloc
or (parsed.scheme != "https" and not loopback)):
raise ExternalOAuthError("oauth_redirect_uri_invalid")
clean.append(uri)
return tuple(dict.fromkeys(clean))
def _normalise_state(value) -> str:
if not isinstance(value, str) or not 16 <= len(value) <= 512 or any(ord(c) < 32 for c in value):
raise ExternalOAuthError("oauth_state_invalid")
return value
def _normalise_challenge(value, method) -> str:
if method != "S256" or not isinstance(value, str) or not 43 <= len(value) <= 128:
raise ExternalOAuthError("oauth_pkce_required")
allowed = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
if any(char not in allowed for char in value):
raise ExternalOAuthError("oauth_pkce_required")
return value
def _normalise_verifier(value) -> str:
if not isinstance(value, str) or not 43 <= len(value) <= 128:
raise ExternalOAuthError("oauth_invalid_grant")
allowed = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
if any(char not in allowed for char in value):
raise ExternalOAuthError("oauth_invalid_grant")
return value
def _normalise_scopes(value, access: str) -> tuple[str, ...]:
requested = str(value or "mcp:read offline_access").split()
requested = list(dict.fromkeys(requested))
if (not requested or any(scope not in SCOPES for scope in requested)
or "mcp:read" not in requested
or ("mcp:write" in requested and access != external_access.ACCESS_READWRITE)):
raise ExternalOAuthError("oauth_scope_invalid")
return tuple(requested)
def normalise_resource(value) -> str:
"""Canonicalise one RFC 8707 audience URI while rejecting ambiguous targets."""
if not isinstance(value, str) or not value.strip() or len(value.strip()) > 1000:
raise ExternalOAuthError("oauth_resource_invalid")
parsed = urlsplit(value.strip())
if (parsed.scheme.lower() not in {"http", "https"} or not parsed.netloc
or parsed.fragment or parsed.username or parsed.password):
raise ExternalOAuthError("oauth_resource_invalid")
try:
port = parsed.port
except ValueError as exc:
raise ExternalOAuthError("oauth_resource_invalid") from exc
hostname = (parsed.hostname or "").lower()
if not hostname:
raise ExternalOAuthError("oauth_resource_invalid")
host = f"[{hostname}]" if ":" in hostname else hostname
netloc = host + (f":{port}" if port is not None else "")
return urlunsplit((parsed.scheme.lower(), netloc, parsed.path, parsed.query, ""))
def _comparison_material(record, prefix: str) -> tuple[bool, bytes, str]:
usable = isinstance(record, dict) and record.get("algo") == ALGORITHM
if usable:
try:
salt = bytes.fromhex(str(record.get(prefix + "_salt") or ""))
expected = str(record.get(prefix + "_hash") or "")
if len(salt) != 32 or len(expected) != 64:
raise ValueError("bad digest")
int(expected, 16)
return True, salt, expected
except (TypeError, ValueError):
pass
return False, _DUMMY_SALT, _DUMMY_HASH
def _used_refresh_history(record, secret: str) -> tuple[bool, list[dict], bool]:
"""Validate and compare every consumed token retained for this live family."""
rows = record.get("used_refresh", ()) if isinstance(record, dict) else ()
if not isinstance(rows, list) or len(rows) > MAX_REFRESH_ROTATIONS:
return False, [], False
valid = True
matched = False
for item in rows:
usable, salt, expected = _comparison_material({
"algo": item.get("algo") if isinstance(item, dict) else None,
"used_salt": item.get("salt") if isinstance(item, dict) else None,
"used_hash": item.get("hash") if isinstance(item, dict) else None,
}, "used")
valid = valid and usable
matched = hmac.compare_digest(_digest(salt, secret), expected) and usable or matched
return valid, list(rows), matched
def _token(prefix: str, tenant: str, identifier: str, secret: str) -> str:
return f"{prefix}.{tenant}.{identifier}.{secret}"
def _parse_token(token, prefixes) -> tuple[str, str, str, str]:
parts = str(token or "").strip().split(".")
if (len(parts) != 4 or parts[0] not in prefixes or not all(parts[1:])
or len(parts[1]) > 128 or len(parts[2]) > 128 or len(parts[3]) > 256):
raise ExternalOAuthAuthError(AUTH_ERROR)
return parts[0], parts[1].lower(), parts[2], parts[3]
def _metadata(record: dict, client: dict | None = None) -> dict:
return {
"id": record.get("id"),
"client_id": record.get("client_id"),
"label": (client or {}).get("label"),
"created": _iso(record.get("created_at")),
"last_used": _iso(record.get("last_used_at")),
"expires_at": _iso(record.get("refresh_expires_at")),
"disconnected_at": _iso(record.get("disconnected_at")),
"access": record.get("access", external_access.ACCESS_READ),
"databases": (external_access.ALL_DATABASES if record.get("databases") == external_access.ALL_DATABASES
else list(record.get("databases") or [])),
"scopes": list(record.get("scopes") or ()),
}
def _client_metadata(record: dict) -> dict:
access, databases = external_access.scope_of(record)
return {
"id": record.get("id"), "label": record.get("label"),
"redirect_uris": list(record.get("redirect_uris") or []),
"created": _iso(record.get("created_at")), "revoked_at": _iso(record.get("revoked_at")),
"access": access,
"databases": (external_access.ALL_DATABASES if databases == external_access.ALL_DATABASES
else list(databases)),
"token_endpoint_auth_method": "none", "pkce": "S256",
}
def register_client(st, username: str, tenant: str, label, redirect_uris, *, access=None,
databases=None) -> dict:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
external_access.resolve_active_user(owner, tenant_key)
clean_label = external_access._normalise_label(label)
redirects = _normalise_redirect_uris(redirect_uris)
clean_access = external_access.normalise_access(access)
clean_databases = external_access.normalise_databases(databases)
created = _now()
made = {}
def _set(value):
book = _book_value(value)
clients = dict(book["clients"])
client_id = "lpc_" + secrets.token_urlsafe(18)
while client_id in clients:
client_id = "lpc_" + secrets.token_urlsafe(18)
record = {
"id": client_id, "username": owner, "tenant": tenant_key, "label": clean_label,
"redirect_uris": list(redirects), "access": clean_access,
"databases": (external_access.ALL_DATABASES if clean_databases == external_access.ALL_DATABASES
else list(clean_databases)),
"created_at": created, "revoked_at": None,
}
clients[client_id] = record
book["clients"] = clients
made["record"] = record
return book
_update(st, _set)
return _client_metadata(made["record"])
def adopt_dynamic_client(st, username: str, tenant: str, client_id: str, label,
redirect_uris, *, access, databases) -> dict:
"""Bind a dynamically registered public client to the user who approved it (HOTFIX 2026-09-24).
RFC 7591 registration happens before anyone signs in, so it carries no tenant and no owner:
the route mints a SIGNED client id and stores nothing. The consent screen is the first moment
both are known, and this writes the ordinary client record under them, so `exchange_code`,
`refresh` and `verify_access` read it exactly as they read a client made in the AI API pane.
⛔ An id already bound to ANOTHER user is refused, never taken over.
"""
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
external_access.resolve_active_user(owner, tenant_key)
clean_label = external_access._normalise_label(label)
redirects = _normalise_redirect_uris(redirect_uris)
clean_access = external_access.normalise_access(access)
clean_databases = external_access.normalise_databases(databases)
stored = (external_access.ALL_DATABASES if clean_databases == external_access.ALL_DATABASES
else list(clean_databases))
made = {}
def _set(value):
book = _book_value(value)
clients = dict(book["clients"])
current = clients.get(client_id)
if isinstance(current, dict) and (current.get("username") != owner
or current.get("tenant") != tenant_key
or current.get("revoked_at")):
raise ExternalOAuthError("oauth_client_invalid")
record = dict(current) if isinstance(current, dict) else {
"id": client_id, "username": owner, "tenant": tenant_key, "created_at": _now(),
"revoked_at": None, "dynamic": True,
}
record.update({"label": clean_label, "redirect_uris": list(redirects),
"access": clean_access, "databases": stored})
clients[client_id] = record
book["clients"] = clients
made["record"] = record
return book
_update(st, _set)
return _client_metadata(made["record"])
def list_clients(st, username: str, tenant: str) -> list[dict]:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
return sorted([
_client_metadata(row) for row in _book(st)["clients"].values()
if isinstance(row, dict) and row.get("username") == owner
and row.get("tenant") == tenant_key and not row.get("revoked_at")
], key=lambda row: str(row.get("created") or ""), reverse=True)
def edit_client(st, username: str, tenant: str, client_id: str, *, label=_UNSET,
redirect_uris=_UNSET, access=_UNSET, databases=_UNSET) -> dict:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
external_access.resolve_active_user(owner, tenant_key)
if label is redirect_uris is access is databases is _UNSET:
raise ExternalOAuthError("oauth_edit_empty")
clean_label = external_access._normalise_label(label) if label is not _UNSET else _UNSET
clean_redirects = _normalise_redirect_uris(redirect_uris) if redirect_uris is not _UNSET else _UNSET
clean_access = external_access.normalise_access(access) if access is not _UNSET else _UNSET
clean_databases = external_access.normalise_databases(databases) if databases is not _UNSET else _UNSET
edited = {}
def _set(value):
book = _book_value(value)
clients = dict(book["clients"])
current = clients.get(client_id)
if (not isinstance(current, dict) or current.get("username") != owner
or current.get("tenant") != tenant_key or current.get("revoked_at")):
raise ExternalOAuthError("oauth_client_not_found")
row = dict(current)
if clean_label is not _UNSET:
row["label"] = clean_label
if clean_redirects is not _UNSET:
row["redirect_uris"] = list(clean_redirects)
if clean_access is not _UNSET:
row["access"] = clean_access
if clean_databases is not _UNSET:
row["databases"] = (external_access.ALL_DATABASES
if clean_databases == external_access.ALL_DATABASES
else list(clean_databases))
clients[client_id] = row
book["clients"] = clients
edited["record"] = row
return book
_update(st, _set)
return _client_metadata(edited["record"])
def authorize(st, username: str, tenant: str, *, client_id, redirect_uri, state,
code_challenge, code_challenge_method, resource, scope=None, response_type="code",
now=None) -> dict:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
external_access.resolve_active_user(owner, tenant_key)
if response_type != "code":
raise ExternalOAuthError("oauth_response_type_invalid")
clean_state = _normalise_state(state)
challenge = _normalise_challenge(code_challenge, code_challenge_method)
audience = normalise_resource(resource)
issued_at = _now(now)
code_id, secret, salt = secrets.token_urlsafe(18), secrets.token_urlsafe(32), secrets.token_bytes(32)
issued = {}
def _set(value):
book = _book_value(value)
client = book["clients"].get(client_id)
if (not isinstance(client, dict) or client.get("username") != owner
or client.get("tenant") != tenant_key or client.get("revoked_at")):
raise ExternalOAuthError("oauth_client_invalid")
if redirect_uri not in (client.get("redirect_uris") or []):
raise ExternalOAuthError("oauth_redirect_uri_invalid")
# R15/C5: approval delegates the live account authority. Saved client settings and
# old grants remain readable metadata, never a cap on a future Manage users change.
access, databases = external_access.ACCESS_READWRITE, external_access.ALL_DATABASES
scopes = _normalise_scopes(scope, access)
states = {key: row for key, row in book["states"].items()
if isinstance(row, dict) and float(row.get("expires_at") or 0) >= issued_at}
state_id = hashlib.sha256(f"{tenant_key}\0{owner}\0{client_id}\0{clean_state}".encode()).hexdigest()
if state_id in states:
raise ExternalOAuthError("oauth_state_replayed")
states[state_id] = {"expires_at": issued_at + CODE_TTL_SECONDS}
codes = {key: row for key, row in book["codes"].items()
if isinstance(row, dict) and float(row.get("expires_at") or 0) >= issued_at - CODE_TTL_SECONDS}
row = {
"id": code_id, "tenant": tenant_key, "username": owner, "client_id": client_id,
"redirect_uri": redirect_uri, "state_hash": _state_digest(clean_state),
"code_challenge": challenge, "resource": audience,
"scopes": list(scopes), "access": access,
"databases": (external_access.ALL_DATABASES if databases == external_access.ALL_DATABASES
else list(databases)),
"code_salt": salt.hex(), "code_hash": _digest(salt, secret), "algo": ALGORITHM,
"created_at": issued_at, "expires_at": issued_at + CODE_TTL_SECONDS,
"consumed_at": None,
}
codes[code_id] = row
book.update({"states": states, "codes": codes})
issued["record"] = row
return book
_update(st, _set)
return {"redirect_uri": redirect_uri, "state": clean_state,
"code": _token("lpc1", tenant_key, code_id, secret),
"expires_in": CODE_TTL_SECONDS}
def exchange_code(code, *, client_id, redirect_uri, code_verifier, resource,
runtime_resolver, now=None) -> dict:
_, tenant_key, code_id, secret = _parse_token(code, {"lpc1"})
verifier = _normalise_verifier(code_verifier)
audience = normalise_resource(resource)
try:
st = runtime_resolver(tenant_key)
external_access._assert_bound_runtime(st, tenant_key)
except (KeyError, external_access.ExternalAccessError) as exc:
raise ExternalOAuthError("oauth_invalid_grant") from exc
snapshot = _book(st)
candidate = snapshot["codes"].get(code_id)
if isinstance(candidate, dict):
try:
external_access.resolve_active_user(candidate.get("username"), tenant_key)
except external_access.ExternalAccessError as exc:
raise ExternalOAuthError("oauth_invalid_grant") from exc
issued_at = _now(now)
access_secret, refresh_secret = secrets.token_urlsafe(32), secrets.token_urlsafe(32)
access_salt, refresh_salt = secrets.token_bytes(32), secrets.token_bytes(32)
grant_id = secrets.token_urlsafe(18)
result = {}
def _set(value):
book = _book_value(value)
row = book["codes"].get(code_id)
usable, salt, expected = _comparison_material(row, "code")
matched = hmac.compare_digest(_digest(salt, secret), expected)
client = book["clients"].get(client_id)
if (not usable or not matched or not isinstance(row, dict) or row.get("consumed_at")
or float(row.get("expires_at") or 0) < issued_at
or row.get("tenant") != tenant_key or row.get("client_id") != client_id
or row.get("redirect_uri") != redirect_uri
or row.get("resource") != audience
or not isinstance(client, dict) or client.get("revoked_at")
or client.get("username") != row.get("username")
or not hmac.compare_digest(_pkce_challenge(verifier), str(row.get("code_challenge") or ""))):
raise ExternalOAuthError("oauth_invalid_grant")
grants = dict(book["grants"])
while grant_id in grants:
raise ExternalOAuthError("oauth_unavailable")
grant = {
"id": grant_id, "tenant": tenant_key, "username": row["username"],
"client_id": client_id, "resource": audience,
"access": row["access"], "databases": row["databases"],
"scopes": list(row["scopes"]), "algo": ALGORITHM,
"access_salt": access_salt.hex(), "access_hash": _digest(access_salt, access_secret),
"refresh_salt": refresh_salt.hex(), "refresh_hash": _digest(refresh_salt, refresh_secret),
"used_refresh": [], "refresh_generation": 0,
"created_at": issued_at, "access_expires_at": issued_at + ACCESS_TTL_SECONDS,
"refresh_expires_at": issued_at + REFRESH_TTL_SECONDS,
"last_used_at": None, "disconnected_at": None,
}
grants[grant_id] = grant
codes = dict(book["codes"])
consumed = dict(row)
consumed["consumed_at"] = issued_at
codes[code_id] = consumed
book.update({"codes": codes, "grants": grants})
result["grant"] = grant
return book
_update(st, _set)
grant = result["grant"]
return {
"token_type": "Bearer", "access_token": _token("lpo1", tenant_key, grant_id, access_secret),
"expires_in": ACCESS_TTL_SECONDS,
"refresh_token": _token("lpr1", tenant_key, grant_id, refresh_secret),
"scope": " ".join(grant["scopes"]),
}
def refresh(refresh_token, *, client_id, resource, runtime_resolver, now=None) -> dict:
_, tenant_key, grant_id, secret = _parse_token(refresh_token, {"lpr1"})
try:
st = runtime_resolver(tenant_key)
external_access._assert_bound_runtime(st, tenant_key)
except (KeyError, external_access.ExternalAccessError) as exc:
raise ExternalOAuthError("oauth_invalid_grant") from exc
snapshot = _book(st)
candidate = snapshot["grants"].get(grant_id)
if isinstance(candidate, dict):
try:
external_access.resolve_active_user(candidate.get("username"), tenant_key)
except external_access.ExternalAccessError as exc:
raise ExternalOAuthError("oauth_invalid_grant") from exc
issued_at = _now(now)
audience = normalise_resource(resource)
next_access, next_refresh = secrets.token_urlsafe(32), secrets.token_urlsafe(32)
next_access_salt, next_refresh_salt = secrets.token_bytes(32), secrets.token_bytes(32)
result = {}
def _set(value):
book = _book_value(value)
grants = dict(book["grants"])
row = grants.get(grant_id)
current_ok, current_salt, current_hash = _comparison_material(row, "refresh")
current_match = hmac.compare_digest(_digest(current_salt, secret), current_hash)
history_ok, used, used_match = _used_refresh_history(row, secret)
if (isinstance(row, dict) and not history_ok and not row.get("disconnected_at")):
corrupted = dict(row)
corrupted["disconnected_at"] = issued_at
grants[grant_id] = corrupted
book["grants"] = grants
result["error"] = "oauth_invalid_grant"
return book
if (isinstance(row, dict) and used_match and not row.get("disconnected_at")):
replayed = dict(row)
replayed["disconnected_at"] = issued_at
grants[grant_id] = replayed
book["grants"] = grants
result["error"] = "oauth_refresh_replayed"
return book
# HOTFIX 2026-09-24: a public client that omits client_id on refresh is the client the
# grant was issued to; the refresh token, matched below, is the credential.
named = client_id or (row.get("client_id") if isinstance(row, dict) else None)
client = book["clients"].get(named)
if (not current_ok or not current_match or not isinstance(row, dict)
or row.get("disconnected_at") or row.get("tenant") != tenant_key
or row.get("client_id") != named
or row.get("resource") != audience
or float(row.get("refresh_expires_at") or 0) < issued_at
or not isinstance(client, dict) or client.get("revoked_at")
or client.get("username") != row.get("username")):
raise ExternalOAuthError("oauth_invalid_grant")
generation = int(row.get("refresh_generation") or 0)
if generation >= MAX_REFRESH_ROTATIONS or len(used) >= MAX_REFRESH_ROTATIONS:
exhausted = dict(row)
exhausted["disconnected_at"] = issued_at
grants[grant_id] = exhausted
book["grants"] = grants
result["error"] = "oauth_refresh_exhausted"
return book
used.append({"salt": row.get("refresh_salt"), "hash": row.get("refresh_hash"),
"algo": ALGORITHM})
rotated = dict(row)
rotated.update({
"used_refresh": used,
"refresh_generation": generation + 1,
"access_salt": next_access_salt.hex(),
"access_hash": _digest(next_access_salt, next_access),
"refresh_salt": next_refresh_salt.hex(),
"refresh_hash": _digest(next_refresh_salt, next_refresh),
"access_expires_at": issued_at + ACCESS_TTL_SECONDS,
"last_used_at": None,
})
grants[grant_id] = rotated
book["grants"] = grants
result["grant"] = rotated
return book
_update(st, _set)
if result.get("error"):
raise ExternalOAuthError(result["error"])
grant = result["grant"]
return {
"token_type": "Bearer", "access_token": _token("lpo1", tenant_key, grant_id, next_access),
"expires_in": ACCESS_TTL_SECONDS,
"refresh_token": _token("lpr1", tenant_key, grant_id, next_refresh),
"scope": " ".join(grant["scopes"]),
}
def _intersect_databases(left, right):
if left == external_access.ALL_DATABASES:
return right
if right == external_access.ALL_DATABASES:
return left
allowed = set(right or ())
return tuple(item for item in (left or ()) if item in allowed)
def _live_permission_user(username: str, tenant: str) -> dict:
"""Read and validate the raw account before its public projection can discard bad perms."""
records = users.registry()
record = records.get(username) if isinstance(records, dict) else None
if not isinstance(record, dict) or record.get("active", True) is not True:
raise ExternalOAuthAuthError(AUTH_ERROR)
version = record.get("perms_v", 0)
if type(version) is not int or version < 0:
raise ExternalOAuthAuthError(AUTH_ERROR)
block = record.get("perms", {})
if not isinstance(block, dict):
raise ExternalOAuthAuthError(AUTH_ERROR)
for key, entry in block.items():
if not isinstance(key, str) or not key or not isinstance(entry, dict):
raise ExternalOAuthAuthError(AUTH_ERROR)
if "access" in entry and type(entry["access"]) is not bool:
raise ExternalOAuthAuthError(AUTH_ERROR)
if "metrics" in entry and type(entry["metrics"]) is not bool:
raise ExternalOAuthAuthError(AUTH_ERROR)
tree = entry.get("filter")
if tree is not None and (not isinstance(tree, dict)
or not isinstance(tree.get("nodes"), list)
or tree.get("conj", "and") not in {"and", "or"}):
raise ExternalOAuthAuthError(AUTH_ERROR)
if "hiddenFields" in entry and (not isinstance(entry["hiddenFields"], list)
or any(not isinstance(field, str) for field in entry["hiddenFields"])):
raise ExternalOAuthAuthError(AUTH_ERROR)
modules = record.get("modules", "all")
if modules != "all" and (not isinstance(modules, (list, tuple))
or any(not isinstance(key, str) or not key for key in modules)):
raise ExternalOAuthAuthError(AUTH_ERROR)
public = users._public(username, record)
if public.get("tenant") != tenant:
raise ExternalOAuthAuthError(AUTH_ERROR)
return public
def _live_permission_scope(user: dict, st) -> tuple[str, object]:
"""C5: resolve this call's database and editor authority, without reading database rows.
The canonical evaluators preserve migrated topic denies and the distinct ut_* share rule.
The coarse write capability also permits owned Sheet work; each writer still checks its
own object, database, row and field authority. Neither client nor grant snapshots enter.
"""
if perms.is_admin(user):
return external_access.ACCESS_READWRITE, external_access.ALL_DATABASES
definitions = st.get_projection(user_tables.STORE_KEY, drop=user_tables.DEF_ONLY_DROPS)
if definitions is None:
definitions = {}
if not isinstance(definitions, dict) or any(
not isinstance(key, str) or not isinstance(value, dict)
for key, value in definitions.items()):
raise ExternalOAuthAuthError(AUTH_ERROR)
# The native activity database has no stored definition; admit it as every other door does.
definitions = user_tables._with_activity(definitions)
grants = st.get(shares.SHARES_KEY, fresh=True)
if grants is None:
grants = {}
if not isinstance(grants, dict):
raise ExternalOAuthAuthError(AUTH_ERROR)
if "database" in grants and not isinstance(grants["database"], dict):
raise ExternalOAuthAuthError(AUTH_ERROR)
lent = user_tables.lend(st, **{user_tables.STORE_KEY: definitions, shares.SHARES_KEY: grants})
topics = {row["key"] for row in registry.governable_modules().values()
if perms.tenant_has_module(st, row["key"])}
candidates = topics | {key for key in definitions if key.startswith(user_tables.KEY_PREFIX)}
databases = tuple(key for key in sorted(candidates) if perm_scope.may_read(user, key, st=lent))
editable = any(key in topics or user_tables.may_edit_database(
key, user["username"], st=lent) for key in databases)
editable = editable or (perms.tenant_has_module(st, "sheets")
and perm_scope.nav_may_open(user, "sheets", st=lent))
return (external_access.ACCESS_READWRITE if editable else external_access.ACCESS_READ), databases
def verify_access(token: str, *, resource, runtime_resolver) -> VerifiedOAuth:
try:
_, tenant_key, grant_id, secret = _parse_token(token, {"lpo1"})
try:
st = runtime_resolver(tenant_key)
external_access._assert_bound_runtime(st, tenant_key)
except KeyError as exc:
raise ExternalOAuthAuthError(AUTH_ERROR) from exc
book = _book(st)
audience = normalise_resource(resource)
row = book["grants"].get(grant_id)
usable, salt, expected = _comparison_material(row, "access")
matched = hmac.compare_digest(_digest(salt, secret), expected)
client = book["clients"].get(row.get("client_id")) if isinstance(row, dict) else None
now = _now()
if (not usable or not matched or not isinstance(row, dict) or row.get("disconnected_at")
or row.get("tenant") != tenant_key or float(row.get("access_expires_at") or 0) < now
or row.get("resource") != audience
or not isinstance(client, dict) or client.get("revoked_at")
or client.get("username") != row.get("username")
or client.get("tenant") != tenant_key):
raise ExternalOAuthAuthError(AUTH_ERROR)
public = _live_permission_user(row["username"], tenant_key)
access, databases = _live_permission_scope(public, st)
scopes = ("mcp:read",) + (("mcp:write",) if external_access.may_write(access) else ())
if "offline_access" in (row.get("scopes") or ()):
scopes += ("offline_access",)
if now - float(row.get("last_used_at") or 0) >= _STAMP_EVERY:
def _stamp(value):
latest = _book_value(value)
grants = dict(latest["grants"])
current = grants.get(grant_id)
if (not isinstance(current, dict) or current.get("disconnected_at")
or current.get("access_hash") != row.get("access_hash")):
raise ExternalOAuthAuthError(AUTH_ERROR)
current = dict(current)
current["last_used_at"] = now
grants[grant_id] = current
latest["grants"] = grants
return latest
_update(st, _stamp, auth=True)
return VerifiedOAuth(tenant_key, grant_id, row["client_id"], public, st, access,
databases, scopes, audience)
except ExternalOAuthAuthError:
raise
except Exception as exc:
raise ExternalOAuthAuthError(AUTH_ERROR) from exc
def disconnect(token: str, *, runtime_resolver, now=None) -> DisconnectedOAuth:
prefix, tenant_key, grant_id, secret = _parse_token(token, {"lpo1", "lpr1"})
try:
st = runtime_resolver(tenant_key)
external_access._assert_bound_runtime(st, tenant_key)
except (KeyError, external_access.ExternalAccessError) as exc:
raise ExternalOAuthAuthError(AUTH_ERROR) from exc
stopped = {}
at = _now(now)
material = "access" if prefix == "lpo1" else "refresh"
def _set(value):
book = _book_value(value)
grants = dict(book["grants"])
row = grants.get(grant_id)
usable, salt, expected = _comparison_material(row, material)
if (not usable or not hmac.compare_digest(_digest(salt, secret), expected)
or not isinstance(row, dict) or row.get("tenant") != tenant_key
or not isinstance(row.get("username"), str) or not row.get("username")):
raise ExternalOAuthAuthError(AUTH_ERROR)
disconnected = dict(row)
if not disconnected.get("disconnected_at"):
disconnected["disconnected_at"] = at
grants[grant_id] = disconnected
book["grants"] = grants
stopped["record"] = disconnected
stopped["client"] = book["clients"].get(disconnected.get("client_id"))
return book
_update(st, _set, auth=True)
record = stopped["record"]
return DisconnectedOAuth(tenant_key, record["username"],
_metadata(record, stopped.get("client")))
def disconnect_for_user(st, username: str, tenant: str, grant_id: str) -> dict:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
stopped = {}
at = _now()
def _set(value):
book = _book_value(value)
grants = dict(book["grants"])
row = grants.get(grant_id)
if (not isinstance(row, dict) or row.get("username") != owner
or row.get("tenant") != tenant_key):
raise ExternalOAuthError("oauth_connection_not_found")
disconnected = dict(row)
if not disconnected.get("disconnected_at"):
disconnected["disconnected_at"] = at
grants[grant_id] = disconnected
book["grants"] = grants
stopped["record"] = disconnected
stopped["client"] = book["clients"].get(disconnected.get("client_id"))
return book
_update(st, _set)
return _metadata(stopped["record"], stopped.get("client"))
def list_connections(st, username: str, tenant: str) -> list[dict]:
owner, tenant_key = external_access._normalise_owner(username, tenant)
external_access._assert_bound_runtime(st, tenant_key)
book = _book(st)
return sorted([
_metadata(row, book["clients"].get(row.get("client_id")))
for row in book["grants"].values()
if isinstance(row, dict) and row.get("username") == owner
and row.get("tenant") == tenant_key and not row.get("disconnected_at")
], key=lambda row: str(row.get("created") or ""), reverse=True)
def label_for(st, grant_id: str) -> str:
book = _book(st)
grant = book["grants"].get(grant_id)
client = book["clients"].get(grant.get("client_id")) if isinstance(grant, dict) else None
if (not isinstance(grant, dict) or grant.get("disconnected_at")
or not isinstance(client, dict) or client.get("revoked_at")):
raise ExternalOAuthAuthError(AUTH_ERROR)
label = client.get("label")
if not isinstance(label, str) or not label:
raise ExternalOAuthError("oauth_unavailable")
return label
def _book_value(value) -> dict:
if value is None:
return {"clients": {}, "codes": {}, "states": {}, "grants": {}}
if not isinstance(value, dict):
raise ExternalOAuthError("oauth_unavailable")
book = dict(value)
for key in ("clients", "codes", "states", "grants"):
child = book.get(key, {})
if not isinstance(child, dict):
raise ExternalOAuthError("oauth_unavailable")
book[key] = dict(child)
return book
def _update(st, callback, *, auth=False) -> None:
try:
st.update(BUCKET, callback, flush="sync")
except (ExternalOAuthError, ExternalOAuthAuthError):
raise
except Exception as exc:
if auth:
raise ExternalOAuthAuthError(AUTH_ERROR) from exc
raise ExternalOAuthError("oauth_unavailable") from exc