sibyllabs's picture
Snapshot mirror of Sibyl-Labs/Sibyl-Memory@8d15cd20b37ce79f39953f684b88b17b2f8e753e
a6a68bb
Raw History Blame Contribute Delete
14.4 kB
"""Test support for the Sibyl Memory plugin family (spec account-gated 4.4, D4).
Two things live here and ONLY here:
``NullEntitlementGate``
An always-``fresh`` gate for unit tests of code that is not about the
account gate. It is a constructor-injected object
(``MemoryClient.local(..., entitlement_gate=NullEntitlementGate())``); no
environment variable, config file or MCP argument can select it. The CLI's
``sibyl memory`` / ``sibyl migrate`` use it on purpose: they read the
person's own local data with no account (D2).
``TestSigner`` + ``install_entitled_home``
What each repo's ``tests/conftest.py`` uses to exercise the REAL gate: a
throwaway Ed25519 keypair whose public key the fixture monkeypatches into
``sibyl_memory_client._entitlement.TRUSTED_KEYS``, and a writer that puts a
``credentials.json`` plus a valid ``entitlement.json`` into an isolated
fake home. The production pinned key is untouched; a token minted here
verifies only while a test has patched its key in.
Nothing in this module weakens the gate for a real install: a fork can inject
a null gate exactly as easily as it can delete the module (spec 1.2).
"""
from __future__ import annotations
import base64
import json
import os
import time
from pathlib import Path
from typing import Any
from ._entitlement import (
Decision,
RefreshOutcome,
STATE_FILENAME,
_trusted,
device_hash,
kid_of,
)
class NullEntitlementGate:
"""Always ``fresh``; the tier comes from the credentials hint (the client
falls back to it because ``tier`` is None here)."""
credentials_path = None
tier = None
cap_bytes = None
token = None
def evaluate(self, op: str | None = None, *, allow_blocking: bool = True) -> Decision:
return Decision("fresh")
def prime(self) -> Decision:
return Decision("fresh")
def current(self) -> Decision:
return Decision("fresh")
def peek(self) -> Decision:
return Decision("fresh")
def peek_token(self) -> None:
return None
def require(self, op: str | None = None) -> None:
return None
def refresh(self, blocking: bool = True) -> RefreshOutcome:
return RefreshOutcome("shared")
def notify_server_rejected(self, code: str | None = None) -> None:
return None
def trusted_kids(self) -> list[str]:
return sorted(_trusted())
def status(self) -> dict[str, Any]:
return {"state": "fresh", "code": None, "notice": None,
"kids": self.trusted_kids()}
def _b64url(data: bytes) -> str:
return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
TEST_ACCOUNT_ID = "11111111-2222-4333-8444-555555555555"
TEST_SESSION_TOKEN = "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
class TestSigner:
"""A throwaway Ed25519 keypair that mints SE1 tokens for tests."""
__test__ = False # not a pytest test class
def __init__(self) -> None:
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
self._key = Ed25519PrivateKey.generate()
self.public_raw = self._key.public_key().public_bytes(
serialization.Encoding.Raw, serialization.PublicFormat.Raw)
self.kid = kid_of(self.public_raw)
@property
def trusted(self) -> dict[str, bytes]:
return {self.kid: self.public_raw}
def payload(self, *, account_id: str = TEST_ACCOUNT_ID,
session_token: str = TEST_SESSION_TOKEN, tenant_id: str | None = None,
now: float | None = None, **overrides: Any) -> dict[str, Any]:
iat = int(time.time() if now is None else now)
p: dict[str, Any] = {
"v": 1, "kid": self.kid, "sub": account_id,
"ten": tenant_id or account_id, "dh": device_hash(session_token),
"tier": "free", "cap": 5242880, "src": "free",
"iat": iat, "nbf": iat - 300, "exp": iat + 604800,
"og": 604800, "ra": 86400, "mem": "full",
"acct": {"complete": True, "email_verified": True, "email_required": False,
"grace_until": None, "enforced": False, "purchase_blocked": False},
"iss": "api.sibyllabs.org",
}
p.update(overrides)
return p
def sign_payload(self, payload: dict[str, Any]) -> str:
seg = _b64url(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
msg = f"SE1.{seg}".encode("ascii")
return f"SE1.{seg}.{_b64url(self._key.sign(msg))}"
def mint(self, **kw: Any) -> str:
return self.sign_payload(self.payload(**kw))
def refresh_fn(self, **mint_kw: Any):
"""A refresh transport that mints a fresh token for whoever asks (the
offline stand-in for POST /api/plugin/entitlement)."""
def _fn(account_id: str, session_token: str) -> RefreshOutcome:
return RefreshOutcome("ok", token=self.mint(
account_id=account_id, session_token=session_token, **mint_kw))
return _fn
def write_credentials(directory: str | Path, *, account_id: str = TEST_ACCOUNT_ID,
session_token: str | None = TEST_SESSION_TOKEN,
tenant_id: str | None = None, tier: str = "free",
**extra: Any) -> Path:
d = Path(directory)
d.mkdir(parents=True, exist_ok=True)
creds: dict[str, Any] = {"account_id": account_id, "tenant_id": tenant_id or account_id,
"tier": tier, "schema_version": 3}
if session_token is not None:
creds["session_token"] = session_token
creds.update(extra)
p = d / "credentials.json"
p.write_text(json.dumps(creds), encoding="utf-8")
os.chmod(p, 0o600)
return p
def write_entitlement(directory: str | Path, token: str, *, received_at: float | None = None,
skew: float | None = None, **extra: Any) -> Path:
now = time.time() if received_at is None else received_at
state: dict[str, Any] = {"token": token, "received_at": now,
"skew": 0.0 if skew is None else skew, "hwm": now}
state.update(extra)
p = Path(directory) / STATE_FILENAME
p.write_text(json.dumps(state), encoding="utf-8")
os.chmod(p, 0o600)
return p
def install_entitled_home(home: str | Path, signer: TestSigner, **mint_kw: Any) -> Path:
"""Write ~/.sibyl-memory/{credentials,entitlement}.json under ``home`` for
the test account, the token signed by ``signer``. Returns the directory."""
d = Path(home) / ".sibyl-memory"
d.mkdir(parents=True, exist_ok=True, mode=0o700)
write_credentials(d)
write_entitlement(d, signer.mint(**mint_kw))
return d
def patch_trusted_keys(monkeypatch: Any, signer: TestSigner, *, keep_pinned: bool = False) -> None:
"""Point the gate at ``signer``'s key (pytest ``monkeypatch``), and route
every refresh through the signer so no test ever reaches the network."""
from . import _entitlement
keys = dict(_entitlement.TRUSTED_KEYS) if keep_pinned else {}
keys.update(signer.trusted)
monkeypatch.setattr(_entitlement, "TRUSTED_KEYS", keys)
monkeypatch.setattr(_entitlement, "http_refresh", signer.refresh_fn())
# Every non-loopback connection or name lookup the guard refused, in order.
# The conftests fail any test that adds to it (a refused attempt a test
# swallowed is still a test that tried to reach a live service).
_REFUSED: list[str] = []
def _is_loopback_host(host: str) -> bool:
"""Exact loopback check: an IP literal that is loopback (127/8, ::1) or the
unspecified address (which connects locally), or the name ``localhost``.
A prefix test would let ``localhost.example.com`` or ``127.evil.test``
through."""
import ipaddress
h = (host or "").strip().lower().strip("[]")
if h == "localhost":
return True
try:
ip = ipaddress.ip_address(h.split("%", 1)[0])
except ValueError:
return False
if getattr(ip, "ipv4_mapped", None) is not None:
ip = ip.ipv4_mapped
return ip.is_loopback or ip.is_unspecified
def refused_connections() -> list[str]:
"""The hosts the guard refused so far in this process (a copy)."""
return list(_REFUSED)
def clear_refused_connections(n_from: int = 0) -> None:
"""Forget refusals recorded from index ``n_from`` on (for the guard's own
self-test, which provokes them on purpose)."""
del _REFUSED[n_from:]
def forbid_external_network(monkeypatch: Any) -> None:
"""Refuse every non-loopback socket connection AND name lookup for the
test's duration, so no suite can reach a live service (api.sibyllabs.org
included) by accident, and record each refusal (``refused_connections``)
so a test that catches the error still fails. Loopback stays open for the
in-process HTTP servers the transport tests use."""
import socket
real_connect = socket.socket.connect
real_connect_ex = socket.socket.connect_ex
real_getaddrinfo = socket.getaddrinfo
real_create_connection = socket.create_connection
def _host(address: Any) -> str:
if isinstance(address, tuple) and address:
host = address[0]
if isinstance(host, bytes):
host = host.decode("ascii", "replace")
return str(host)
return str(address)
def _check(address: Any) -> None:
if isinstance(address, (str, bytes)): # AF_UNIX path
return
host = _host(address)
if not _is_loopback_host(host):
_REFUSED.append(host)
raise ConnectionRefusedError(f"test network guard: refused {host}")
def connect(self, address): # type: ignore[no-untyped-def]
if getattr(self, "family", None) != getattr(socket, "AF_UNIX", object()):
_check(address)
return real_connect(self, address)
def connect_ex(self, address): # type: ignore[no-untyped-def]
if getattr(self, "family", None) != getattr(socket, "AF_UNIX", object()):
_check(address)
return real_connect_ex(self, address)
def getaddrinfo(host, *args, **kwargs): # type: ignore[no-untyped-def]
name = host.decode("ascii", "replace") if isinstance(host, bytes) else host
if name not in (None, "") and not _is_loopback_host(str(name)):
_REFUSED.append(str(name))
raise socket.gaierror(socket.EAI_NONAME,
f"test network guard: refused lookup of {name}")
return real_getaddrinfo(host, *args, **kwargs)
def create_connection(address, *args, **kwargs): # type: ignore[no-untyped-def]
_check(address)
return real_create_connection(address, *args, **kwargs)
monkeypatch.setattr(socket.socket, "connect", connect)
monkeypatch.setattr(socket.socket, "connect_ex", connect_ex)
monkeypatch.setattr(socket, "getaddrinfo", getaddrinfo)
monkeypatch.setattr(socket, "create_connection", create_connection)
def assert_no_external_attempts(start: int) -> None:
"""Raise AssertionError when refusals were recorded since index ``start``
(the conftests call this after every test)."""
new = _REFUSED[start:]
if new:
hosts = sorted(set(new))
del _REFUSED[start:]
raise AssertionError(
"test tried to open a non-loopback connection (refused by the test "
f"network guard): {hosts}")
# ---- real-home guard (save/debloat build, 2026-09-27) -----------------------
# The lifecycle, the skills installer, the hook wiring and the Claude Code /
# Codex / Hermes shims write under the home directory. Tests must only ever
# see a temporary HOME. The conftests assert, per test, that HOME is not the
# account's real home, and at session end that none of the paths this build
# writes changed under the real home.
REAL_HOME_WATCHED = (
".sibyl-memory/lifecycle.json", ".sibyl-memory/lifecycle.log", ".sibyl-memory/lifecycle.lock",
".sibyl-memory/signals.json",
".sibyl-memory/skills", ".sibyl-memory/debloat", ".sibyl-memory/debloat.json",
".sibyl-memory/debloat.lock",
".claude/skills/sibyl-save", ".claude/skills/sibyl-debloat", ".claude/settings.json",
".codex/AGENTS.md", ".codex/prompts/sibyl-save.md", ".codex/prompts/sibyl-debloat.md",
".codex/config.toml", ".hermes/skills/sibyl-save", ".hermes/skills/sibyl-debloat",
)
def real_home() -> Path:
"""The account's home from the password database (never ``$HOME``)."""
import pwd
return Path(pwd.getpwuid(os.getuid()).pw_dir)
def real_home_snapshot() -> dict[str, Any]:
"""(exists, size, mtime_ns) per watched path, plus whether the real
``~/.claude/settings.json`` mentions a sibyl hook."""
home = real_home()
snap: dict[str, Any] = {}
for rel in REAL_HOME_WATCHED:
p = home / rel
try:
st = p.lstat()
snap[rel] = (True, st.st_size, st.st_mtime_ns)
except OSError:
snap[rel] = (False, 0, 0)
try:
txt = (home / ".claude" / "settings.json").read_text(encoding="utf-8", errors="replace")
snap["settings_has_sibyl_hook"] = "sibyl-hook" in txt or " hook session-start" in txt
except OSError:
snap["settings_has_sibyl_hook"] = False
return snap
def real_home_changes(before: dict[str, Any]) -> list[str]:
after = real_home_snapshot()
changed = [k for k in before if before.get(k) != after.get(k)]
# settings.json belongs to the person's own Claude Code and changes for
# reasons of its own: only a NEW sibyl hook in it counts against a test.
changed = [k for k in changed if k != ".claude/settings.json"]
return changed
def assert_home_is_not_real() -> None:
home = Path(os.path.expanduser("~")).resolve()
if home == real_home().resolve():
raise AssertionError("a test ran with HOME pointing at the real home directory")
__all__ = [
"NullEntitlementGate", "TestSigner", "assert_home_is_not_real", "assert_no_external_attempts",
"clear_refused_connections", "forbid_external_network", "real_home", "real_home_changes",
"real_home_snapshot", "refused_connections",
"TEST_ACCOUNT_ID", "TEST_SESSION_TOKEN",
"install_entitled_home", "patch_trusted_keys", "write_credentials",
"write_entitlement",
]