loopable / platform /core /external_access.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
a5981db verified
Raw History Blame Contribute Delete
25.4 kB
"""Per-user credentials carrying an access level and database subset for governed reads and
builds, with the maker's live grants still applying on top.
Verification reconstructs the same PUBLIC user record the normal API session carries, so every
later database read still goes through ``perm_scope`` and the existing Assistant mirror.
This module never reads product rows and never caches a
credential, user, bucket, or tenant runtime.
"""
import calendar
from dataclasses import dataclass
from datetime import datetime, timezone
import hashlib
import hmac
import logging
import os
import secrets
import time
import core.users as users
from harness import runtime
_log = logging.getLogger(__name__)
BUCKET = "external_access"
ACCESS_READ = "read"
ACCESS_READWRITE = "readwrite"
ACCESS_REFRESH = "refresh"
ACCESS_LEVELS = (ACCESS_READ, ACCESS_READWRITE, ACCESS_REFRESH)
ALL_DATABASES = "all"
MAX_SCOPE_DATABASES = 200
MAX_SCOPE_WORKBOOKS = 100
ALGORITHM = "sha256-salt-v1"
AUTH_ERROR = "invalid_external_credential"
_UNSET = object()
_DUMMY_SALT = bytes(32)
_DUMMY_HASH = hashlib.sha256(_DUMMY_SALT + b"invalid").hexdigest()
#: Seconds between two durable `last_used` stamps for ONE credential.
#:
#: ⛔⛔ THE STAMP IS THROTTLED, AND THIS IS NOT AN OPTIMISATION. `st.update(..., flush="sync")` is
#: a fresh strict read plus a BLOCKING UPLOAD, i.e. one durable commit per verified request. An
#: external AI reads in bursts and the store's budget is 256 commits an hour, so an unthrottled
#: stamp would spend a tenant's whole write budget on telemetry and put an upload inside the
#: latency of every read. It would also make a surface contract C7 calls READ ONLY write on every
#: single call, which is the claim this module exists to keep true. The pane renders `last_used` to
#: the minute, so a quarter of an hour of staleness costs the reader nothing.
#: ⚠ REVOCATION IS NOT THROTTLED AND MUST NEVER BE: `revoke` and `mint` stay `flush="sync"`, and
#: verification still reads the bucket FRESH on every request, which is what makes "revoking stops
#: the next request" true.
_STAMP_EVERY = 900.0
class ExternalAccessError(RuntimeError):
"""A stable core-layer refusal. HTTP status and copy belong to the API layer."""
def __init__(self, code: str):
super().__init__(code)
self.code = code
class ExternalAuthError(ExternalAccessError):
"""A uniform authentication refusal that reveals no credential or tenant detail."""
def __init__(self, code: str, *, cause: str = "unknown_key"):
super().__init__(code)
self.cause = cause
def normalise_access(value, *, allow_refresh=False) -> str:
if value is None or value == "":
return ACCESS_READWRITE
if value in ACCESS_LEVELS and (value != ACCESS_REFRESH or allow_refresh):
return value
raise ExternalAccessError("external_access_scope_invalid")
def normalise_test_connection(value) -> bool:
"""Require an explicit boolean when a caller sets the test restriction."""
if type(value) is not bool:
raise ExternalAccessError("external_test_connection_invalid")
return value
def normalise_databases(value):
if value is None or (isinstance(value, str) and value.strip().lower() == ALL_DATABASES):
return ALL_DATABASES
if not isinstance(value, (list, tuple)) or not 1 <= len(value) <= MAX_SCOPE_DATABASES:
raise ExternalAccessError("external_databases_invalid")
if any(not isinstance(item, str) or not item.strip() or len(item.strip()) > 200
for item in value):
raise ExternalAccessError("external_databases_invalid")
return tuple(dict.fromkeys(item.strip() for item in value))
def scope_of(record):
"""Read legacy defaults, but preserve a stored empty subset as no database access."""
record = record if isinstance(record, dict) else {}
access = record.get("access")
if access not in ACCESS_LEVELS:
access = ACCESS_READWRITE
databases = record.get("databases")
if isinstance(databases, (list, tuple)):
databases = tuple(item.strip() for item in databases
if isinstance(item, str) and item.strip())
else:
databases = ALL_DATABASES
return access, databases
def normalise_workbooks(value):
"""Accept a bounded workbook allowlist, with no implicit wildcard."""
if value is None:
return ()
if (not isinstance(value, (list, tuple)) or len(value) > MAX_SCOPE_WORKBOOKS
or any(not isinstance(item, str) or not item.strip() or len(item.strip()) > 200
or item.strip() == "all" for item in value)):
raise ExternalAccessError("external_workbooks_invalid")
return tuple(dict.fromkeys(item.strip() for item in value))
def workbooks_of(record):
"""Treat absent or malformed stored workbook grants as no refresh access."""
try:
return normalise_workbooks(record.get("workbooks"))
except (AttributeError, ExternalAccessError):
return ()
def may_write(access) -> bool:
return access == ACCESS_READWRITE
def database_allowed(databases, database) -> bool:
if databases == ALL_DATABASES:
return True
return isinstance(database, str) and bool(database.strip()) and database.strip() in databases
@dataclass(frozen=True)
class VerifiedCredential:
"""The authenticated public principal plus the request-scoped tenant runtime."""
tenant: str
key_id: str
user: dict
runtime: object
access: str = ACCESS_READWRITE
databases: object = ALL_DATABASES
workbooks: tuple = ()
warning: str | None = None
origin_recorded: bool = False
def _now() -> str:
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
def _epoch(value: str | None) -> float | None:
if value is None:
return None
try:
return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(
tzinfo=timezone.utc).timestamp()
except (TypeError, ValueError, OverflowError):
return None
def normalise_expiry(value, *, now: float | None = None) -> str | None:
"""Return one canonical future UTC expiry, or ``None`` for no expiry."""
if value is None or value == "":
return None
if not isinstance(value, str):
raise ExternalAccessError("external_expiry_invalid")
parsed = _epoch(value.strip())
if parsed is None or parsed <= (time.time() if now is None else float(now)):
raise ExternalAccessError("external_expiry_invalid")
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(parsed))
def _stamp_is_due(last_used, now: float) -> bool:
"""Is this credential's `last_used` stale enough to be worth a durable write?
An absent, unparseable or future stamp is DUE, so a corrupt value self-heals on the next
request rather than freezing the field forever.
"""
if not last_used:
return True
try:
seen = calendar.timegm(time.strptime(str(last_used), "%Y-%m-%dT%H:%M:%SZ"))
except (TypeError, ValueError):
return True
return not (0.0 <= now - seen < _STAMP_EVERY)
def _digest(salt: bytes, secret: str) -> str:
"""Hash one external secret with SHA-256 and its per-record random salt.
The secret has 256 bits of machine-generated randomness, not human-password entropy. A slow
password KDF therefore buys nothing against an offline attacker and would deliberately delay
every request on the read surface.
"""
return hashlib.sha256(salt + secret.encode("utf-8")).hexdigest()
def _book(st, *, fresh: bool = True) -> dict:
try:
value = st.get(BUCKET, fresh=fresh)
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
if value is None:
return {}
if not isinstance(value, dict):
raise ExternalAccessError("external_access_unavailable")
return value
def _normalise_owner(username: str, tenant: str) -> tuple[str, str]:
owner = str(username or "").strip().lower()
tenant_key = str(tenant or "").strip().lower()
if not owner or not tenant_key:
raise ExternalAccessError("external_identity_invalid")
return owner, tenant_key
def _assert_bound_runtime(st, tenant: str) -> None:
if str(getattr(st, "key", "") or "").strip().lower() != tenant:
raise ExternalAccessError("external_identity_invalid")
def resolve_active_user(username: str, tenant: str) -> dict:
try:
registry = users.registry() or {}
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
if not isinstance(registry, dict):
raise ExternalAccessError("external_access_unavailable")
record = registry.get(username)
if not isinstance(record, dict) or not record.get("active", True):
raise ExternalAccessError("external_account_unavailable")
public = users._public(username, record)
if public.get("tenant") != tenant:
raise ExternalAccessError("external_account_unavailable")
return public
def _active_public_user(username: str, tenant: str) -> dict:
"""Backward-compatible private spelling retained for the SDLC 62 seam."""
return resolve_active_user(username, tenant)
def _normalise_label(label) -> str:
clean = str(label or "").strip()
if (not clean or len(clean) > 80 or any(ord(char) < 32 for char in clean)
or "lpb1." in clean or "lpo1." in clean or "lpr1." in clean
or "lpc1." in clean):
raise ExternalAccessError("external_label_invalid")
return clean
def _metadata(record: dict) -> dict:
"""Return list-safe metadata. Salt, digest, algorithm and owner never cross this seam."""
access, databases = scope_of(record)
return {
"id": record.get("id"),
"label": record.get("label"),
"created": record.get("created"),
"last_used": record.get("last_used"),
"revoked_at": record.get("revoked_at"),
"rotated_at": record.get("rotated_at"),
"expires_at": record.get("expires_at"),
"access": access,
"databases": ALL_DATABASES if databases == ALL_DATABASES else list(databases),
"workbooks": list(workbooks_of(record)),
"test_connection": record.get("test_connection", False) is not False,
}
def label_for(st, key_id: str) -> str:
"""Read only a verified key's label from its tenant runtime, never credential material."""
record = _book(st).get(key_id)
if not isinstance(record, dict) or record.get("revoked_at"):
raise ExternalAuthError(AUTH_ERROR)
label = record.get("label")
if not isinstance(label, str) or not label:
raise ExternalAccessError("external_access_unavailable")
return label
def is_test_connection(st, key_id: str) -> bool:
"""Read the current test restriction without returning credential material."""
record = _book(st).get(key_id)
if not isinstance(record, dict) or record.get("revoked_at"):
raise ExternalAuthError(AUTH_ERROR)
return record.get("test_connection", False) is not False
def mint(st, username: str, tenant: str, label: str, access=None, databases=None,
expires_at=None, test_connection=False, workbooks=None) -> tuple[dict, str]:
"""Create one credential and return ``(metadata, token)``; the token is never persisted."""
access = normalise_access(access, allow_refresh=True)
databases = normalise_databases(databases)
workbooks = normalise_workbooks(workbooks)
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
_active_public_user(owner, tenant_key)
clean_label = _normalise_label(label)
expiry = normalise_expiry(expires_at)
test_connection = normalise_test_connection(test_connection)
secret = secrets.token_urlsafe(32)
salt = secrets.token_bytes(32)
created = _now()
minted: dict = {}
def _set(value):
if value is None:
book = {}
elif isinstance(value, dict):
book = dict(value)
else:
raise ExternalAccessError("external_access_unavailable")
key_id = secrets.token_urlsafe(18)
while key_id in book:
key_id = secrets.token_urlsafe(18)
record = {
"id": key_id,
"username": owner,
"tenant": tenant_key,
"label": clean_label,
"access": access,
"databases": ALL_DATABASES if databases == ALL_DATABASES else list(databases),
"workbooks": list(workbooks),
"salt": salt.hex(),
"hash": _digest(salt, secret),
"algo": ALGORITHM,
"created": created,
"last_used": None,
"revoked_at": None,
"rotated_at": None,
"expires_at": expiry,
"test_connection": test_connection,
"minted_space": os.environ.get("SPACE_ID") or None,
}
book[key_id] = record
minted["record"] = record
return book
try:
st.update(BUCKET, _set, flush="sync")
except ExternalAccessError:
raise
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
record = minted.get("record")
if not isinstance(record, dict):
raise ExternalAccessError("external_access_unavailable")
token = f"lpb1.{tenant_key}.{record['id']}.{secret}"
return _metadata(record), token
def edit(st, username: str, tenant: str, key_id: str, *, label=_UNSET, access=_UNSET,
databases=_UNSET, expires_at=_UNSET, test_connection=_UNSET, workbooks=_UNSET) -> dict:
"""Edit metadata/scope in one store update; credential material is left untouched."""
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
resolve_active_user(owner, tenant_key)
target = str(key_id or "").strip()
if label is access is databases is expires_at is test_connection is workbooks is _UNSET:
raise ExternalAccessError("external_edit_empty")
clean_label = _normalise_label(label) if label is not _UNSET else _UNSET
clean_access = normalise_access(access, allow_refresh=True) if access is not _UNSET else _UNSET
clean_databases = normalise_databases(databases) if databases is not _UNSET else _UNSET
clean_workbooks = normalise_workbooks(workbooks) if workbooks is not _UNSET else _UNSET
clean_expiry = normalise_expiry(expires_at) if expires_at is not _UNSET else _UNSET
clean_test = normalise_test_connection(test_connection) if test_connection is not _UNSET else _UNSET
edited: dict = {}
def _set(value):
if not isinstance(value, dict):
raise ExternalAccessError("external_key_not_found")
book = dict(value)
current = book.get(target)
if (not isinstance(current, dict) or current.get("username") != owner
or current.get("tenant") != tenant_key or current.get("revoked_at")):
raise ExternalAccessError("external_key_not_found")
record = dict(current)
if clean_label is not _UNSET:
record["label"] = clean_label
if clean_access is not _UNSET:
record["access"] = clean_access
if clean_databases is not _UNSET:
record["databases"] = (ALL_DATABASES if clean_databases == ALL_DATABASES
else list(clean_databases))
if clean_workbooks is not _UNSET:
record["workbooks"] = list(clean_workbooks)
if clean_expiry is not _UNSET:
record["expires_at"] = clean_expiry
if clean_test is not _UNSET:
record["test_connection"] = clean_test
book[target] = record
edited["record"] = record
return book
try:
st.update(BUCKET, _set, flush="sync")
except ExternalAccessError:
raise
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
record = edited.get("record")
if not isinstance(record, dict):
raise ExternalAccessError("external_access_unavailable")
return _metadata(record)
def rotate(st, username: str, tenant: str, key_id: str) -> tuple[dict, str]:
"""Replace one owned key's secret atomically and reveal the replacement exactly once."""
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
resolve_active_user(owner, tenant_key)
target = str(key_id or "").strip()
secret = secrets.token_urlsafe(32)
salt = secrets.token_bytes(32)
rotated: dict = {}
def _set(value):
if not isinstance(value, dict):
raise ExternalAccessError("external_key_not_found")
book = dict(value)
current = book.get(target)
if (not isinstance(current, dict) or current.get("username") != owner
or current.get("tenant") != tenant_key or current.get("revoked_at")):
raise ExternalAccessError("external_key_not_found")
record = dict(current)
record.update({
"salt": salt.hex(), "hash": _digest(salt, secret), "algo": ALGORITHM,
"rotated_at": _now(), "last_used": None,
"minted_space": os.environ.get("SPACE_ID") or None,
})
book[target] = record
rotated["record"] = record
return book
try:
st.update(BUCKET, _set, flush="sync")
except ExternalAccessError:
raise
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
record = rotated.get("record")
if not isinstance(record, dict):
raise ExternalAccessError("external_access_unavailable")
return _metadata(record), f"lpb1.{tenant_key}.{target}.{secret}"
def list_for_user(st, username: str, tenant: str) -> list[dict]:
"""List only this user's active credential metadata, newest first."""
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
records = [
_metadata(record)
for record in _book(st).values()
if isinstance(record, dict)
and record.get("username") == owner
and record.get("tenant") == tenant_key
and not record.get("revoked_at")
]
return sorted(records, key=lambda row: str(row.get("created") or ""), reverse=True)
def revoke(st, username: str, tenant: str, key_id: str) -> dict:
"""Tombstone one credential owned by this user; foreign and absent IDs are identical."""
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
target = str(key_id or "").strip()
revoked: dict = {}
def _set(value):
if not isinstance(value, dict):
raise ExternalAccessError("external_key_not_found")
book = dict(value)
current = book.get(target)
if (not isinstance(current, dict)
or current.get("username") != owner
or current.get("tenant") != tenant_key):
raise ExternalAccessError("external_key_not_found")
record = dict(current)
if not record.get("revoked_at"):
record["revoked_at"] = _now()
book[target] = record
revoked["record"] = record
return book
try:
st.update(BUCKET, _set, flush="sync")
except ExternalAccessError:
raise
except Exception as exc:
raise ExternalAccessError("external_access_unavailable") from exc
record = revoked.get("record")
if not isinstance(record, dict):
raise ExternalAccessError("external_access_unavailable")
return _metadata(record)
def _parse_token(token: str) -> tuple[str, str, str]:
parts = str(token or "").strip().split(".")
if (len(parts) != 4 or parts[0] != "lpb1" or not all(parts[1:])
or len(parts[1]) > 128 or len(parts[2]) > 128 or len(parts[3]) > 256):
raise ExternalAuthError(AUTH_ERROR)
return parts[1].lower(), parts[2], parts[3]
def _comparison_material(record) -> tuple[bool, bytes, str]:
usable = isinstance(record, dict) and record.get("algo") == ALGORITHM
if usable:
try:
salt = bytes.fromhex(str(record.get("salt") or ""))
expected = str(record.get("hash") or "")
if len(salt) != 32 or len(expected) != 64:
raise ValueError("bad credential digest")
int(expected, 16)
return True, salt, expected
except (TypeError, ValueError):
pass
return False, _DUMMY_SALT, _DUMMY_HASH
def _recorded_space(record: dict) -> str | None:
"""Treat missing or malformed origin metadata as unproved."""
value = record.get("minted_space")
return value if isinstance(value, str) and value.strip() else None
def _credential_cause(record, tenant: str, key_id: str, secret: str, *, owner=None):
"""Inspect status only after the secret and optional session owner match the stored record."""
material_ok, salt, expected = _comparison_material(record)
matched = hmac.compare_digest(_digest(salt, secret), expected)
if (not material_ok or not matched or record.get("id") != key_id
or record.get("tenant") != tenant or not record.get("username")
or (owner is not None and record.get("username") != owner)):
return "unknown_key"
origin, current = _recorded_space(record), os.environ.get("SPACE_ID")
if origin and current and origin != current:
return "minted_elsewhere"
if record.get("revoked_at"):
return "revoked"
if record.get("expires_at"):
expiry = _epoch(record["expires_at"])
if expiry is None or expiry <= time.time():
return "expired"
return None
def verify_for_owner(st, username: str, tenant: str, token: str) -> dict:
"""Diagnose only a session owner's secret inside that session's tenant runtime."""
owner, tenant_key = _normalise_owner(username, tenant)
_assert_bound_runtime(st, tenant_key)
try:
verified = verify(token, owner_runtime=st, owner=owner)
except ExternalAuthError as exc:
return {"valid": False, "cause": exc.cause, "warning": None, "origin_recorded": None}
return {"valid": True, "cause": None, "warning": verified.warning,
"origin_recorded": verified.origin_recorded, "key_id": verified.key_id}
def verify(token: str, *, owner_runtime=None, owner=None) -> VerifiedCredential:
"""Verify a bearer token from fresh state and resolve its ordinary public-user principal."""
try:
tenant_key, key_id, secret = _parse_token(token)
if owner_runtime is not None:
if not owner or getattr(owner_runtime, "key", None) != tenant_key:
raise ExternalAuthError(AUTH_ERROR)
st = owner_runtime
else:
try:
st = runtime.get_runtime(tenant_key)
except KeyError as exc:
raise ExternalAuthError(AUTH_ERROR) from exc
book = _book(st)
record = book.get(key_id)
cause = _credential_cause(record, tenant_key, key_id, secret, owner=owner)
if cause:
raise ExternalAuthError(AUTH_ERROR, cause=cause)
owner = str(record["username"]).strip().lower()
try:
public = _active_public_user(owner, tenant_key)
except ExternalAccessError as exc:
raise ExternalAuthError(AUTH_ERROR) from exc
access, databases = scope_of(record)
if not _stamp_is_due(record.get("last_used"), time.time()):
return VerifiedCredential(tenant=tenant_key, key_id=key_id, user=public, runtime=st,
access=access, databases=databases, workbooks=workbooks_of(record),
origin_recorded=bool(_recorded_space(record)))
used_at = _now()
def _stamp(value):
if not isinstance(value, dict):
raise ExternalAuthError(AUTH_ERROR)
current = value.get(key_id)
cause = _credential_cause(current, tenant_key, key_id, secret, owner=owner)
if cause:
raise ExternalAuthError(AUTH_ERROR, cause=cause)
book_now = dict(value)
stamped = dict(current)
stamped["last_used"] = used_at
book_now[key_id] = stamped
return book_now
warning = None
try:
st.update(BUCKET, _stamp, flush="sync")
except ExternalAuthError:
raise
except Exception as exc:
# Store diagnostics must not include credential material or exception text.
_log.warning("external_access last_used stamp failed: %s", type(exc).__name__)
warning = "store_write_refused"
return VerifiedCredential(tenant=tenant_key, key_id=key_id, user=public, runtime=st,
access=access, databases=databases, workbooks=workbooks_of(record),
warning=warning, origin_recorded=bool(_recorded_space(record)))
except ExternalAuthError:
raise
except ExternalAccessError as exc:
if owner_runtime is not None:
raise
raise ExternalAuthError(AUTH_ERROR) from exc
except Exception as exc:
raise ExternalAuthError(AUTH_ERROR) from exc