One call before every side effect.

"""Reality Kernel reference client — POST /v1/check with Ed25519 verification."""
from __future__ import annotations

import base64
import os
import uuid
from dataclasses import dataclass, field

import httpx
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey


class RealityKernelError(RuntimeError):
    """Transport / auth / credit failure. Treat as BLOCK — the engine never fails open."""


class ActionBlocked(PermissionError):
    def __init__(self, verdict: "Verdict"):
        super().__init__(f"BLOCK {verdict.action_id}: {'; '.join(verdict.evidence)}")
        self.verdict = verdict


class ActionNeedsReview(RuntimeError):
    def __init__(self, verdict: "Verdict"):
        super().__init__(f"WARN {verdict.action_id}: operator review required")
        self.verdict = verdict


@dataclass(frozen=True)
class Verdict:
    action_id: str
    verdict: str                      # "ALLOW" | "WARN" | "BLOCK"
    confidence: float
    evidence: list[str]
    proof_hash: str
    ed25519_signature: str
    ed25519_pubkey: str
    latency_ms: float = 0.0
    credits_consumed: int = 0
    credits_remaining: int = 0
    raw: dict = field(default_factory=dict, repr=False)

    @property
    def sign_data(self) -> str:
        # Canonical string the server signed. Python str() of a float is the wire format.
        return f"{self.action_id}:{self.proof_hash}:{self.verdict}:{self.confidence}"

    def verify(self, pinned_pubkey_b64: str | None = None) -> bool:
        """Verify the Ed25519 seal. Pass your pinned key from GET /v1/pubkey in production."""
        pub_b64 = pinned_pubkey_b64 or self.ed25519_pubkey
        pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(pub_b64))
        try:
            pub.verify(base64.b64decode(self.ed25519_signature), self.sign_data.encode())
            return True
        except InvalidSignature:
            return False


class RealityKernel:
    def __init__(
        self,
        api_key: str | None = None,
        base_url: str | None = None,
        agent_id: str | None = None,
        timeout: float = 10.0,
    ):
        self.api_key  = api_key  or os.environ["RK_API_KEY"]
        self.base_url = (base_url or os.environ.get("RK_BASE_URL", "https://www.realitykernel.dev")).rstrip("/")
        self.agent_id = agent_id or os.environ.get("RK_AGENT_ID", "")
        self._http = httpx.Client(
            base_url=self.base_url,
            timeout=timeout,
            headers={"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"},
        )
        self._pubkey_b64: str | None = None

    # ── Public key (pin once per process) ──────────────────────────────
    def pubkey(self) -> str:
        if self._pubkey_b64 is None:
            r = self._http.get("/v1/pubkey")            # no auth required
            r.raise_for_status()
            self._pubkey_b64 = r.json()["public_key"]
        return self._pubkey_b64

    # ── Core check ────────────────────────────────────────────────────
    def check(
        self,
        command: str,
        prime_intent: str,
        *,
        session_id: str = "",
        policy: dict | None = None,
        idempotency_key: str | None = None,
        verify_signature: bool = True,
    ) -> Verdict:
        body = {
            "command": command,
            "prime_intent": prime_intent,
            "session_id": session_id,
            "agent_id": self.agent_id,
        }
        if policy:
            body["policy"] = policy               # {"allowed_tools": [...], "allowed_egress": [...]}
        headers = {"Idempotency-Key": idempotency_key or uuid.uuid4().hex}

        try:
            r = self._http.post("/v1/check", json=body, headers=headers)
        except httpx.HTTPError as e:
            raise RealityKernelError(f"transport failure: {e}") from e

        if r.status_code == 402:
            raise RealityKernelError("insufficient credits — treat as BLOCK")
        if r.status_code == 429:
            raise RealityKernelError("rate limited — back off and retry, do not execute")
        if r.status_code >= 400:
            raise RealityKernelError(f"HTTP {r.status_code}: {r.json().get('detail', r.text)}")

        j = r.json()
        v = Verdict(
            action_id=j["action_id"], verdict=j["verdict"], confidence=float(j["confidence"]),
            evidence=list(j.get("evidence", [])), proof_hash=j["proof_hash"],
            ed25519_signature=j.get("ed25519_signature", ""), ed25519_pubkey=j.get("ed25519_pubkey", ""),
            latency_ms=j.get("latency_ms", 0.0), credits_consumed=j.get("credits_consumed", 0),
            credits_remaining=j.get("credits_remaining", 0), raw=j,
        )
        if verify_signature and not v.verify(self.pubkey()):
            raise RealityKernelError(f"signature verification FAILED for {v.action_id}")
        if r.headers.get("X-RK-Credits-Low") == "true":
            print(f"[reality-kernel] {r.headers.get('X-RK-Credits-Warning')}")
        return v

    # ── Operator override for WARN ─────────────────────────────────────
    def override(self, action_id: str, approved: bool) -> dict:
        r = self._http.post("/v1/override", json={
            "action_id": action_id,
            "decision": "approved" if approved else "rejected",
        })
        r.raise_for_status()
        return r.json()   # {"ok", "verdict": "WARN_APPROVED"|"WARN_REJECTED", "override_action_id", "warning_level"}

    # ── Guard: raise on WARN/BLOCK, return Verdict on ALLOW ────────────
    def guard(self, command: str, prime_intent: str, **kw) -> Verdict:
        v = self.check(command, prime_intent, **kw)
        if v.verdict == "BLOCK":
            raise ActionBlocked(v)
        if v.verdict == "WARN":
            raise ActionNeedsReview(v)
        return v

import { createPublicKey, verify as edVerify, randomUUID } from "node:crypto";

export type VerdictKind = "ALLOW" | "WARN" | "BLOCK";

export interface LeastAgencyPolicy {
  allowed_tools•: string[];
  allowed_egress•: string[];      // exact hosts, IPs, or "*.example.com"
  read_only_paths•: string[];
}

export interface CheckRequest {
  command: string;
  prime_intent: string;
  session_id•: string;
  agent_id•: string;
  policy•: LeastAgencyPolicy;
}

export interface Verdict {
  action_id: string;
  verdict: VerdictKind;
  confidence: number;
  worlds_evaluated: number;
  worlds_in_basin_b: number;
  max_divergence: number;
  evidence: string[];
  proof_hash: string;
  latency_ms: number;
  credits_consumed: number;
  credits_remaining: number;
  ed25519_signature: string;      // base64
  ed25519_pubkey: string;         // base64, raw 32 bytes
}

export class RealityKernelError extends Error {}
export class ActionBlocked extends Error { constructor(public verdict: Verdict) { super(`BLOCK ${verdict.action_id}: ${verdict.evidence.join("; ")}`); } }
export class ActionNeedsReview extends Error { constructor(public verdict: Verdict) { super(`WARN ${verdict.action_id}`); } }

/** Server signs `${action_id}:${proof_hash}:${verdict}:${confidence}` with deterministic canonical confidence encoding. */
export function canonicalConfidence(c: number): string {
  return Number.isInteger(c) • c.toFixed(1) : String(c);   // 1 → "1.0", 0.98 → "0.98"
}

const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");

export function verifyVerdict(v: Verdict, pinnedPubkeyB64•: string): boolean {
  const raw = Buffer.from(pinnedPubkeyB64 •• v.ed25519_pubkey, "base64");
  if (raw.length !== 32) return false;
  const key = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: "der", type: "spki" });
  const msg = `${v.action_id}:${v.proof_hash}:${v.verdict}:${canonicalConfidence(v.confidence)}`;
  return edVerify(null, Buffer.from(msg, "utf8"), key, Buffer.from(v.ed25519_signature, "base64"));
}

export class RealityKernel {
  private pubkey•: string;
  constructor(
    private readonly apiKey = process.env.RK_API_KEY!,
    private readonly baseUrl = (process.env.RK_BASE_URL •• "https://www.realitykernel.dev").replace(/\/$/, ""),
    private readonly agentId = process.env.RK_AGENT_ID •• "",
  ) { if (!apiKey) throw new RealityKernelError("RK_API_KEY not set"); }

  async getPubkey(): Promise<string> {
    if (!this.pubkey) {
      const r = await fetch(`${this.baseUrl}/v1/pubkey`);          // public, no auth
      if (!r.ok) throw new RealityKernelError(`pubkey HTTP ${r.status}`);
      this.pubkey = ((await r.json()) as { public_key: string }).public_key;
    }
    return this.pubkey;
  }

  async check(req: CheckRequest, opts: { idempotencyKey•: string; verify•: boolean; signal•: AbortSignal } = {}): Promise<Verdict> {
    const r = await fetch(`${this.baseUrl}/v1/check`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": opts.idempotencyKey •• randomUUID(),
      },
      body: JSON.stringify({ agent_id: this.agentId, ...req }),
      signal: opts.signal •• AbortSignal.timeout(10_000),
    }).catch((e) => { throw new RealityKernelError(`transport: ${e.message}`); });

    if (r.status === 402) throw new RealityKernelError("insufficient credits — treat as BLOCK");
    if (r.status === 429) throw new RealityKernelError("rate limited — do not execute");
    if (!r.ok) throw new RealityKernelError(`HTTP ${r.status}: ${((await r.json().catch(() => ({}))) as any).detail •• r.statusText}`);

    const v = (await r.json()) as Verdict;
    if (opts.verify !== false && !verifyVerdict(v, await this.getPubkey())) {
      throw new RealityKernelError(`signature verification FAILED for ${v.action_id}`);
    }
    if (r.headers.get("X-RK-Credits-Low") === "true") console.warn("[reality-kernel]", r.headers.get("X-RK-Credits-Warning"));
    return v;
  }

  async override(actionId: string, approved: boolean) {
    const r = await fetch(`${this.baseUrl}/v1/override`, {
      method: "POST",
      headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
      body: JSON.stringify({ action_id: actionId, decision: approved • "approved" : "rejected" }),
    });
    if (!r.ok) throw new RealityKernelError(`override HTTP ${r.status}`);
    return r.json() as Promise<{ ok: boolean; verdict: "WARN_APPROVED" | "WARN_REJECTED"; override_action_id: string; warning_level: "standard" | "critical" }>;
  }

  /** Resolve on ALLOW; throw ActionBlocked / ActionNeedsReview otherwise. */
  async guard(req: CheckRequest): Promise<Verdict> {
    const v = await this.check(req);
    if (v.verdict === "BLOCK") throw new ActionBlocked(v);
    if (v.verdict === "WARN") throw new ActionNeedsReview(v);
    return v;
  }
}