patchr 0.1.0__py3-none-any.whl

picux/sdk/external.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import mimetypes
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from picux.sdk.client import PicuxClient
+
+
+@dataclass(frozen=True)
+class ExternalPricing:
+    successUsd: float = 1.0
+    mgmtRate: float = 0.05
+    mgmtCapUsd: float = 5.0
+
+    def quote(self, *, valueUsd: float = 0.0, laborUsd: float = 0.0) -> dict[str, Any]:
+        value = max(0.0, float(valueUsd or 0.0))
+        labor = max(0.0, float(laborUsd or 0.0))
+        success = self.successUsd if value > 0 else 0.0
+        mgmt = min(labor * max(0.0, self.mgmtRate), max(0.0, self.mgmtCapUsd)) if labor > 0 else 0.0
+        return {
+            "currency": "USD",
+            "valueUsd": round(value, 2),
+            "laborUsd": round(labor, 2),
+            "successFeeUsd": round(success, 2),
+            "mgmtFeeUsd": round(mgmt, 2),
+            "totalFeeUsd": round(success + mgmt, 2),
+            "adapter": "external",
+        }
+
+
+class ExternalAppClient:
+    """External app/service/agent adapter that calls Picux through the SDK boundary."""
+
+    def __init__(self, client: PicuxClient, *, pricing: ExternalPricing | None = None, appId: str = "external") -> None:
+        self.client = client
+        self.pricing = pricing or ExternalPricing()
+        self.appId = appId
+
+    def deployAgent(
+        self,
+        *,
+        goal: str,
+        userId: str = "external",
+        domain: str = "hunt",
+        needsApproval: bool = False,
+        meta: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "userId": userId,
+            "domain": domain,
+            "channel": self.appId,
+            "goal": goal,
+            "needsApproval": needsApproval,
+            "meta": {"appId": self.appId, **(meta or {})},
+        }
+        return self.client.createTask(payload)
+
+    def publishSignal(
+        self,
+        signal: dict[str, Any],
+        *,
+        targetDomain: str = "hunt",
+        userId: str = "external",
+        approved: bool = False,
+    ) -> dict[str, Any]:
+        return self.client.launchCommunityTask(
+            {
+                "userId": userId,
+                "targetDomain": targetDomain,
+                "approved": approved,
+                "signal": signal,
+            }
+        )
+
+    def requestResolve(
+        self,
+        *,
+        text: str,
+        userId: str = "external",
+        requestId: str = "",
+        provider: str = "",
+        location: str = "",
+        issueType: str = "",
+        attachments: list[dict[str, Any]] | None = None,
+        filePaths: list[str] | None = None,
+        contact: dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
+        needsApproval: bool = False,
+    ) -> dict[str, Any]:
+        clean = _redactText(text)
+        contactRefs = _contactRefs(contact or {})
+        encodedFiles = _fileAttachments(filePaths or [])
+        request = {
+            "kind": "resolveRequest",
+            "requestId": requestId,
+            "provider": provider,
+            "location": location,
+            "issueType": issueType,
+            "text": clean,
+            "attachments": [*(attachments or []), *encodedFiles],
+            "contact": contactRefs,
+        }
+        return self.client.createTask(
+            {
+                "userId": userId,
+                "domain": "resolve",
+                "channel": self.appId,
+                "goal": clean,
+                "extRef": requestId,
+                "needsApproval": needsApproval,
+                "inData": {"query": clean, "request": request},
+                "meta": {"appId": self.appId, "requestId": requestId, **(meta or {})},
+            }
+        )
+
+    def requestProxy(
+        self,
+        *,
+        task: str,
+        userId: str = "external",
+        taskId: str = "",
+        kind: str = "review",
+        reason: str = "humanIntervention",
+        context: dict[str, Any] | None = None,
+        requestId: str = "",
+        refs: dict[str, Any] | None = None,
+        proofReq: list[str] | None = None,
+        route: dict[str, Any] | None = None,
+        channelMsg: dict[str, Any] | None = None,
+        voiceCall: dict[str, Any] | None = None,
+        policy: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "userId": userId,
+            "kind": kind,
+            "reason": reason,
+            "task": task,
+            "context": {"appId": self.appId, **(context or {})},
+        }
+        optional = {
+            "taskId": taskId,
+            "requestId": requestId,
+            "refs": refs,
+            "proofReq": proofReq,
+            "route": route,
+            "channelMsg": channelMsg,
+            "voiceCall": voiceCall,
+            "policy": policy,
+        }
+        payload.update({key: value for key, value in optional.items() if value})
+        return self.client.createProxyMission(payload)
+
+    def submitProxy(
+        self,
+        *,
+        proxyId: str = "",
+        requestId: str = "",
+        note: str = "",
+        text: str = "",
+        proof: dict[str, Any] | None = None,
+        refs: dict[str, Any] | None = None,
+        requiresPhysicalProof: bool | None = None,
+        policy: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"appId": self.appId, **(proof or {})}
+        optional = {
+            "requestId": requestId,
+            "note": note,
+            "text": text,
+            "refs": refs,
+            "requiresPhysicalProof": requiresPhysicalProof,
+            "policy": policy,
+        }
+        payload.update({key: value for key, value in optional.items() if value is not None and value != ""})
+        if proxyId:
+            return self.client.submitProxyOutcome(proxyId, payload)
+        return self.client.submitProxyOutcomeByRef(payload)
+
+    def priceOutcome(self, *, valueUsd: float = 0.0, laborUsd: float = 0.0) -> dict[str, Any]:
+        return self.pricing.quote(valueUsd=valueUsd, laborUsd=laborUsd)
+
+
+def _redactText(text: str) -> str:
+    clean = re.sub(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", "[email]", str(text or ""), flags=re.IGNORECASE)
+    return re.sub(r"\+?\b(?:\d[\s().-]?){8,15}\d\b", "[phone]", clean)
+
+
+def _contactRefs(contact: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    emailRef = str(contact.get("emailRef", "") or "")
+    phoneRef = str(contact.get("phoneRef", "") or "")
+    email = str(contact.get("email", "") or "")
+    phone = str(contact.get("phone", contact.get("phoneNumber", "")) or "")
+    if emailRef:
+        result["emailRef"] = emailRef
+    elif email:
+        result["emailRef"] = _hashedRef("email", email)
+    if phoneRef:
+        result["phoneRef"] = phoneRef
+    elif phone:
+        result["phoneRef"] = _hashedRef("phone", phone)
+    if result:
+        result["redacted"] = True
+    if contact.get("preferredChannel"):
+        result["preferredChannel"] = str(contact.get("preferredChannel") or "")
+    return result
+
+
+def _hashedRef(kind: str, value: str) -> str:
+    digest = hashlib.sha256(str(value or "").strip().lower().encode("utf-8")).hexdigest()[:16]
+    return f"external:{kind}:{digest}"
+
+
+def _fileAttachments(filePaths: list[str]) -> list[dict[str, Any]]:
+    attachments: list[dict[str, Any]] = []
+    for rawPath in filePaths:
+        path = Path(rawPath)
+        data = path.read_bytes()
+        attachments.append(
+            {
+                "kind": _kindFromPath(path),
+                "name": path.name,
+                "mime": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
+                "size": len(data),
+                "sha256": "sha256:" + hashlib.sha256(data).hexdigest(),
+                "dataBase64": base64.b64encode(data).decode("ascii"),
+            }
+        )
+    return attachments
+
+
+def _kindFromPath(path: Path) -> str:
+    name = path.name.lower()
+    if "receipt" in name:
+        return "receipt"
+    if "damage" in name or "photo" in name:
+        return "damagePhoto"
+    if "screen" in name:
+        return "screenshot"
+    return "attachment"

picux/security/__init__.py

@@ -0,0 +1,18 @@
+"""Security and production readiness primitives."""
+
+from .auth import AuthResult, PicuxAuthGate
+from .config_validator import ProductionReadiness, assertProductionReady, validateProductionReady
+from .policy import PolicyDecision, PolicyEngine
+from .secrets import SecretResolution, SecretResolver
+
+__all__ = [
+    "AuthResult",
+    "PicuxAuthGate",
+    "PolicyDecision",
+    "PolicyEngine",
+    "ProductionReadiness",
+    "SecretResolution",
+    "SecretResolver",
+    "assertProductionReady",
+    "validateProductionReady",
+]

picux/security/auth.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import hmac
+from dataclasses import dataclass
+from typing import Any
+
+from picux.config import PicuxSettings
+
+
+PUBLIC_ROUTES = {
+    ("GET", "/healthz"),
+    ("GET", "/runtime"),
+    ("GET", "/v1/status"),
+    ("GET", "/openapi.json"),
+    ("GET", "/v1/contract"),
+    ("GET", "/v1/manifest"),
+    ("GET", "/v1/protocol-map"),
+    ("GET", "/v1/a2a/contract"),
+    ("GET", "/v1/pay/adapters/contract"),
+    ("POST", "/v1/handshake"),
+}
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    ok: bool
+    error: str = ""
+    status: int = 200
+    transport: str = "api"
+
+    def toMap(self) -> dict[str, Any]:
+        if self.ok:
+            return {"ok": True, "transport": self.transport}
+        return {"ok": False, "error": self.error, "transport": self.transport}
+
+
+class PicuxAuthGate:
+    """Bearer token gate for external API and MCP transports."""
+
+    def __init__(self, *, apiToken: str = "", mcpToken: str = "", a2aToken: str = "") -> None:
+        self.apiToken = str(apiToken or "").strip()
+        self.mcpToken = str(mcpToken or "").strip()
+        self.a2aToken = str(a2aToken or "").strip()
+
+    @classmethod
+    def fromEnv(cls) -> "PicuxAuthGate":
+        settings = PicuxSettings.fromEnv()
+        return cls(apiToken=settings.apiToken, mcpToken=settings.mcpToken, a2aToken=settings.a2aToken)
+
+    def authorize(self, method: str, path: str, headers: dict[str, Any] | None = None) -> AuthResult:
+        method = method.upper()
+        path = str(path or "/")
+        transport = self._transport(path)
+        if (method, path) in PUBLIC_ROUTES or (method == "GET" and path.startswith("/v1/schemas")):
+            return AuthResult(ok=True, transport=transport)
+
+        expected = self._expectedToken(transport)
+        if not expected:
+            return AuthResult(ok=True, transport=transport)
+        actual = self._bearer(headers or {})
+        if not hmac.compare_digest(actual, expected):
+            return AuthResult(ok=False, error="unauthorized", status=401, transport=transport)
+        return AuthResult(ok=True, transport=transport)
+
+    def _expectedToken(self, transport: str) -> str:
+        if transport == "mcp":
+            return self.mcpToken or self.apiToken
+        if transport == "a2a":
+            return self.a2aToken or self.apiToken
+        return self.apiToken
+
+    @staticmethod
+    def _transport(path: str) -> str:
+        if path == "/mcp":
+            return "mcp"
+        if path.startswith("/v1/a2a"):
+            return "a2a"
+        return "api"
+
+    @staticmethod
+    def _bearer(headers: dict[str, Any]) -> str:
+        normalized = {str(key).lower(): str(value) for key, value in headers.items()}
+        raw = normalized.get("authorization", "").strip()
+        if raw.lower().startswith("bearer "):
+            return raw[7:].strip()
+        return ""

picux/security/config_validator.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from picux.config import PicuxSettings
+
+
+REQUIRED_PROD_FIELDS = {
+    "apiToken": "PICUX_API_TOKEN",
+    "redisUrl": "PICUX_REDIS_URL",
+    "postgresDsn": "PICUX_POSTGRES_DSN",
+    "mcpUrl": "PICUX_MCP_BASE_URL",
+    "mcpToken": "PICUX_MCP_TOKEN",
+    "a2aUrl": "PICUX_A2A_BASE_URL",
+    "a2aToken": "PICUX_A2A_TOKEN",
+    "bridgeUrl": "PICUX_BRIDGE_API_BASE",
+    "bridgeToken": "PICUX_BRIDGE_API_TOKEN",
+    "resolveToken": "PICUX_RESOLVE_OUTCOME_WEBHOOK_TOKEN",
+    "bridgeOutcomeToken": "PICUX_BRIDGE_OUTCOME_WEBHOOK_TOKEN",
+    "vaultKey": "PICUX_VAULT_KEY_B64",
+}
+
+
+@dataclass(frozen=True)
+class ProductionReadiness:
+    ok: bool
+    prod: bool
+    issues: tuple[str, ...]
+
+    def toMap(self) -> dict[str, Any]:
+        return {"ok": self.ok, "prod": self.prod, "issues": list(self.issues)}
+
+
+def validateProductionReady(settings: PicuxSettings) -> ProductionReadiness:
+    if not settings.prod:
+        return ProductionReadiness(ok=True, prod=False, issues=())
+
+    issues: list[str] = []
+    for attr, envName in REQUIRED_PROD_FIELDS.items():
+        value = getattr(settings, attr)
+        if not str(value or "").strip():
+            issues.append(f"missing:{envName}")
+
+    if not settings.policyEnforcement:
+        issues.append("invalid:PICUX_POLICY_ENFORCEMENT")
+    if str(settings.apiUrl or "").startswith("http://127.0.0.1"):
+        issues.append("invalid:PICUX_API_BASE_URL")
+    if str(settings.redisUrl or "").startswith("redis://localhost"):
+        issues.append("invalid:PICUX_REDIS_URL")
+
+    return ProductionReadiness(ok=not issues, prod=True, issues=tuple(issues))
+
+
+def assertProductionReady(settings: PicuxSettings) -> None:
+    readiness = validateProductionReady(settings)
+    if not readiness.ok:
+        raise RuntimeError("productionNotReady:" + ",".join(readiness.issues))

picux/security/policy.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PolicyDecision:
+    allowed: bool
+    reasons: tuple[str, ...]
+    subjectId: str
+    action: str
+    resource: str
+    domain: str
+    mandateId: str = ""
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "allowed": self.allowed,
+            "reasons": list(self.reasons),
+            "subjectId": self.subjectId,
+            "action": self.action,
+            "resource": self.resource,
+            "domain": self.domain,
+            "mandateId": self.mandateId,
+        }
+
+
+class PolicyEngine:
+    """Least-privilege checks for mandate sessions and capability grants."""
+
+    def __init__(self, *, clock: Callable[[], datetime] | None = None) -> None:
+        self.clock = clock or (lambda: datetime.now(timezone.utc))
+
+    def evaluate(self, payload: dict[str, Any]) -> dict[str, Any]:
+        decision = self.decision(payload)
+        return {"ok": decision.allowed, "decision": decision.toMap()}
+
+    def decision(self, payload: dict[str, Any]) -> PolicyDecision:
+        subjectId = str(payload.get("subjectId", payload.get("agentId", payload.get("clientId", ""))) or "")
+        action = str(payload.get("action", "") or "")
+        resource = str(payload.get("resource", "") or "")
+        domain = str(payload.get("domain", "") or "")
+        mandateId = str(payload.get("mandateId", "") or "")
+        povRef = str(payload.get("povRef", payload.get("povId", "")) or "")
+        session = payload.get("session", {}) if isinstance(payload.get("session"), dict) else {}
+        grants = payload.get("grants", []) if isinstance(payload.get("grants"), list) else []
+        reasons: list[str] = []
+
+        if not subjectId:
+            reasons.append("missing:subjectId")
+        if not action:
+            reasons.append("missing:action")
+        if not resource:
+            reasons.append("missing:resource")
+        if not domain:
+            reasons.append("missing:domain")
+        reasons.extend(self._sessionReasons(session, subjectId=subjectId, action=action, domain=domain, mandateId=mandateId))
+        if action.startswith("pay.") and not mandateId:
+            reasons.append("missing:mandateId")
+        if action == "pay.settle" and not povRef:
+            reasons.append("missing:povRef")
+        if not self._grantAllowed(grants, subjectId=subjectId, action=action, resource=resource, domain=domain):
+            reasons.append("grantDenied")
+
+        cleanReasons = tuple(dict.fromkeys(reason for reason in reasons if reason))
+        return PolicyDecision(
+            allowed=not cleanReasons,
+            reasons=cleanReasons,
+            subjectId=subjectId,
+            action=action,
+            resource=resource,
+            domain=domain,
+            mandateId=mandateId,
+        )
+
+    def _sessionReasons(
+        self,
+        session: dict[str, Any],
+        *,
+        subjectId: str,
+        action: str,
+        domain: str,
+        mandateId: str,
+    ) -> list[str]:
+        reasons: list[str] = []
+        if not session:
+            return ["missing:session"]
+        if str(session.get("status", "active") or "active") != "active":
+            reasons.append("sessionInactive")
+        if self._expired(str(session.get("expiresAt", "") or "")):
+            reasons.append("sessionExpired")
+        sessionSubject = str(session.get("subjectId", "") or "")
+        if sessionSubject and subjectId and sessionSubject != subjectId:
+            reasons.append("subjectMismatch")
+        sessionMandate = str(session.get("mandateId", "") or "")
+        if sessionMandate and mandateId and sessionMandate != mandateId:
+            reasons.append("mandateMismatch")
+        domains = _cleanList(session.get("domains", []))
+        if domains and domain and domain not in domains:
+            reasons.append("domainDenied")
+        actions = _cleanList(session.get("actions", []))
+        if actions and action and action not in actions:
+            reasons.append("actionDenied")
+        return reasons
+
+    def _grantAllowed(self, grants: list[Any], *, subjectId: str, action: str, resource: str, domain: str) -> bool:
+        for grant in grants:
+            if not isinstance(grant, dict):
+                continue
+            if self._expired(str(grant.get("expiresAt", "") or "")):
+                continue
+            grantSubject = str(grant.get("subjectId", "") or "")
+            if grantSubject and subjectId and grantSubject != subjectId:
+                continue
+            domains = _cleanList(grant.get("domains", []))
+            if domains and domain not in domains:
+                continue
+            actions = _cleanList(grant.get("actions", []))
+            if action not in actions and "*" not in actions:
+                continue
+            resources = _cleanList(grant.get("resources", []))
+            if resource not in resources and "*" not in resources:
+                continue
+            return True
+        return False
+
+    def _expired(self, value: str) -> bool:
+        parsed = _parseTime(value)
+        return bool(parsed and parsed <= self.clock())
+
+
+def _cleanList(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    deduped: list[str] = []
+    for item in value:
+        clean = str(item or "").strip()
+        if clean and clean not in deduped:
+            deduped.append(clean)
+    return deduped
+
+
+def _parseTime(value: str) -> datetime | None:
+    raw = str(value or "").strip()
+    if not raw:
+        return None
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(raw)
+    except Exception:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)