patchr 0.1.0__py3-none-any.whl

picux/storage/connectors.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import time
+from typing import Any
+
+
+CONNECTOR_KINDS = {"api", "mcp", "a2a", "webhook", "database", "erp", "custom"}
+CONNECTOR_STATUSES = {"active", "paused", "revoked"}
+CONNECTION_SESSION_STATUSES = {"active", "revoked", "expired"}
+CONNECTION_SESSION_MODES = {"clientHostedAdapter", "picuxHostedAdapter", "mcpTool", "webhookCallback"}
+SECRET_KEYS = {"token", "apiKey", "secret", "password", "privateKey", "clientSecret", "value"}
+
+
+class ConnectorBook:
+    """Bridge connector registry with scoped credential references."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+        self._sessions: dict[str, dict[str, Any]] = {}
+
+    def saveConnector(self, payload: dict[str, Any], *, status: str = "active") -> dict[str, Any]:
+        connectorId = str(payload.get("connectorId", payload.get("id", "")) or "")
+        if not connectorId:
+            return {"ok": False, "error": "missing:connectorId"}
+        errors = _connectorErrors(payload)
+        if errors:
+            return {"ok": False, "error": "invalid:connector", "errors": errors}
+        current = self.getConnector(connectorId)
+        now = int(time.time())
+        createdAt = current.get("connector", {}).get("createdAt", now) if current.get("ok") else now
+        record = _recordFromPayload({**payload, "connectorId": connectorId}, status=status, createdAt=createdAt, updatedAt=now)
+        self._saveRecord(record)
+        return {"ok": True, "connector": copy.deepcopy(record)}
+
+    def getConnector(self, connectorId: str) -> dict[str, Any]:
+        connectorId = str(connectorId or "")
+        record = self._records.get(connectorId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchConnector"):
+            record = self.backing.fetchConnector(connectorId)
+            if record:
+                self._records[connectorId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "connectorNotFound", "connectorId": connectorId}
+        return {"ok": True, "connector": copy.deepcopy(record)}
+
+    def listConnectors(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        records = self._filtered(filters)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "connectors": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def matchConnectors(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        filters = filters or {}
+        records = self._filtered({**filters, "status": str(filters.get("status", "active") or "active")})
+        return {"ok": True, "connectors": [copy.deepcopy(record) for record in records], "count": len(records)}
+
+    def updateConnector(self, connectorId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getConnector(connectorId)
+        if not current.get("ok"):
+            return current
+        merged = {**current["connector"], **updates, "connectorId": connectorId}
+        errors = _connectorErrors(merged)
+        if errors:
+            return {"ok": False, "error": "invalid:connector", "errors": errors}
+        record = _recordFromPayload(
+            merged,
+            status=_status(merged.get("status", current["connector"].get("status", "active"))),
+            createdAt=int(current["connector"].get("createdAt", int(time.time())) or int(time.time())),
+            updatedAt=int(updates.get("updatedAt", int(time.time())) or int(time.time())),
+        )
+        self._saveRecord(record)
+        return {"ok": True, "connector": copy.deepcopy(record)}
+
+    def createConnectionSession(self, payload: dict[str, Any]) -> dict[str, Any]:
+        errors = _connectionSessionErrors(payload)
+        if errors:
+            return {"ok": False, "error": "invalid:connectionSession", "errors": errors}
+        connectorId = str(payload.get("connectorId", "") or "")
+        if connectorId and not self.getConnector(connectorId).get("ok"):
+            return {"ok": False, "error": "connectorNotFound", "connectorId": connectorId}
+        now = int(time.time())
+        sessionId = str(payload.get("sessionId", "") or _sessionId(payload, time.time_ns()))
+        record = _connectionSessionFromPayload({**payload, "sessionId": sessionId}, createdAt=now, updatedAt=now)
+        self._saveSession(record)
+        return {"ok": True, "session": copy.deepcopy(record)}
+
+    def getConnectionSession(self, sessionId: str) -> dict[str, Any]:
+        sessionId = str(sessionId or "")
+        record = self._sessions.get(sessionId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchConnectionSession"):
+            record = self.backing.fetchConnectionSession(sessionId)
+            if record:
+                self._sessions[sessionId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "connectionSessionNotFound", "sessionId": sessionId}
+        return {"ok": True, "session": copy.deepcopy(record)}
+
+    def listConnectionSessions(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBackingSessions()
+        filters = filters or {}
+        connectorId = str(filters.get("connectorId", "") or "")
+        status = str(filters.get("status", "") or "")
+        records = list(self._sessions.values())
+        if connectorId:
+            records = [record for record in records if record.get("connectorId") == connectorId]
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("sessionId", ""))), reverse=True)
+        limit = _limit(filters.get("limit", 100))
+        return {"ok": True, "sessions": [copy.deepcopy(record) for record in records[:limit]], "count": min(len(records), limit)}
+
+    def revokeConnectionSession(self, sessionId: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        current = self.getConnectionSession(sessionId)
+        if not current.get("ok"):
+            return current
+        payload = payload or {}
+        record = {
+            **current["session"],
+            "status": "revoked",
+            "revokedReason": str(payload.get("reason", payload.get("revokedReason", "")) or ""),
+            "updatedAt": int(time.time()),
+        }
+        self._saveSession(record)
+        return {"ok": True, "session": copy.deepcopy(record)}
+
+    def _filtered(self, filters: dict[str, Any]) -> list[dict[str, Any]]:
+        self._loadBacking()
+        status = str(filters.get("status", "") or "")
+        kind = str(filters.get("kind", "") or "")
+        domain = str(filters.get("domain", "") or "")
+        cap = str(filters.get("cap", filters.get("capability", "")) or "")
+        caps = _cleanList(filters.get("caps", []))
+        action = str(filters.get("action", "") or "")
+        resource = str(filters.get("resource", "") or "")
+        records = list(self._records.values())
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if kind:
+            records = [record for record in records if record.get("kind") == kind]
+        if domain:
+            records = [record for record in records if record.get("domain") == domain]
+        if cap:
+            records = [record for record in records if cap in record.get("caps", [])]
+        if caps:
+            records = [record for record in records if set(caps).intersection(record.get("caps", []))]
+        if action:
+            records = [record for record in records if _hasScope(record, action=action, resource=resource)]
+        records.sort(key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("connectorId", ""))), reverse=True)
+        return records
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        connectorId = str(record.get("connectorId", "") or "")
+        if not connectorId:
+            return
+        self._records[connectorId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertConnector"):
+            self.backing.upsertConnector(record)
+
+    def _saveSession(self, record: dict[str, Any]) -> None:
+        sessionId = str(record.get("sessionId", "") or "")
+        if not sessionId:
+            return
+        self._sessions[sessionId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertConnectionSession"):
+            self.backing.upsertConnectionSession(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listConnectors"):
+            return
+        for record in self.backing.listConnectors():
+            connectorId = str(record.get("connectorId", "") or "")
+            if connectorId:
+                self._records[connectorId] = copy.deepcopy(record)
+
+    def _loadBackingSessions(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listConnectionSessions"):
+            return
+        for record in self.backing.listConnectionSessions():
+            sessionId = str(record.get("sessionId", "") or "")
+            if sessionId:
+                self._sessions[sessionId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _recordFromPayload(payload: dict[str, Any], *, status: str, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "status": _status(payload.get("status", status)),
+        "domain": str(payload.get("domain", "bridge") or "bridge"),
+        "kind": _kind(payload.get("kind", "api")),
+        "name": str(payload.get("name", payload.get("connectorId", "")) or ""),
+        "endpoint": str(payload.get("endpoint", payload.get("url", "")) or ""),
+        "caps": _cleanList(payload.get("caps", payload.get("capabilities", []))),
+        "credential": _credential(payload.get("credential", payload.get("auth", {}))),
+        "scopes": [_scope(item) for item in payload.get("scopes", []) if isinstance(item, dict)],
+        "payment": _payment(payload.get("payment", payload.get("pricing", {}))),
+        "health": payload.get("health", {}) if isinstance(payload.get("health"), dict) else {},
+        "meta": payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {},
+        "createdAt": int(createdAt or updatedAt),
+        "updatedAt": int(updatedAt or createdAt),
+    }
+
+
+def _connectionSessionFromPayload(payload: dict[str, Any], *, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    return {
+        "sessionId": str(payload.get("sessionId", "") or ""),
+        "connectorId": str(payload.get("connectorId", "") or ""),
+        "status": _connectionSessionStatus(payload.get("status", "active")),
+        "executionMode": _connectionSessionMode(payload.get("executionMode", "clientHostedAdapter")),
+        "subjectId": str(payload.get("subjectId", "") or ""),
+        "credentialRefs": _credentialRefs(payload.get("credentialRefs", [])),
+        "scopes": [_scope(item) for item in payload.get("scopes", []) if isinstance(item, dict)],
+        "callback": _callback(payload.get("callback", {})),
+        "providerMeta": payload.get("providerMeta", {}) if isinstance(payload.get("providerMeta"), dict) else {},
+        "expiresAt": str(payload.get("expiresAt", "") or ""),
+        "createdAt": int(createdAt),
+        "updatedAt": int(updatedAt),
+    }
+
+
+def _connectorErrors(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if _kind(payload.get("kind", "api")) not in CONNECTOR_KINDS:
+        errors.append("invalid:kind")
+    if not str(payload.get("endpoint", payload.get("url", "")) or "").strip():
+        errors.append("missing:endpoint")
+    if _hasRawSecret(payload.get("auth", {})) or _hasRawSecret(payload.get("credential", {})):
+        errors.append("rawSecretNotAllowed")
+    scopes = payload.get("scopes", [])
+    if not isinstance(scopes, list):
+        errors.append("invalid:scopes")
+    else:
+        for idx, scope in enumerate(scopes):
+            if not isinstance(scope, dict):
+                errors.append(f"invalid:scopes.{idx}")
+                continue
+            if not str(scope.get("scopeId", "") or "").strip():
+                errors.append(f"missing:scopes.{idx}.scopeId")
+            if not _cleanList(scope.get("actions", [])):
+                errors.append(f"missing:scopes.{idx}.actions")
+    return errors
+
+
+def _connectionSessionErrors(payload: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not str(payload.get("connectorId", "") or "").strip():
+        errors.append("missing:connectorId")
+    if _hasRawSecret(payload.get("credential", {})) or _hasRawSecret(payload.get("auth", {})):
+        errors.append("rawSecretNotAllowed")
+    if not _credentialRefs(payload.get("credentialRefs", [])):
+        errors.append("missing:credentialRefs")
+    if any(_hasRawSecret(item) for item in payload.get("credentialRefs", []) if isinstance(item, dict)):
+        errors.append("rawSecretNotAllowed")
+    scopes = payload.get("scopes", [])
+    if not isinstance(scopes, list):
+        errors.append("invalid:scopes")
+    else:
+        for idx, scope in enumerate(scopes):
+            if not isinstance(scope, dict):
+                errors.append(f"invalid:scopes.{idx}")
+                continue
+            if not str(scope.get("scopeId", "") or "").strip():
+                errors.append(f"missing:scopes.{idx}.scopeId")
+            if not _cleanList(scope.get("actions", [])):
+                errors.append(f"missing:scopes.{idx}.actions")
+    return errors
+
+
+def _credential(value: Any) -> dict[str, Any]:
+    raw = value if isinstance(value, dict) else {}
+    return {
+        "type": str(raw.get("type", "bearer") or "bearer"),
+        "tokenRef": str(raw.get("tokenRef", raw.get("secretRef", "")) or ""),
+        "env": str(raw.get("env", "") or ""),
+        "rotation": str(raw.get("rotation", "") or ""),
+    }
+
+
+def _payment(value: Any) -> dict[str, Any]:
+    raw = value if isinstance(value, dict) else {}
+    price = raw.get("price", raw.get("amount", {}))
+    price = price if isinstance(price, dict) else {}
+    acceptedRails = raw.get("acceptedRails", raw.get("rails", []))
+    return {
+        "required": bool(raw.get("required", False)),
+        "pricingModel": str(raw.get("pricingModel", "free") or "free"),
+        "price": {
+            "amount": float(price.get("amount", 0.0) or 0.0),
+            "currency": str(price.get("currency", "USD") or "USD").upper(),
+        },
+        "acceptedRails": _cleanList(acceptedRails),
+        "requiresEscrow": bool(raw.get("requiresEscrow", False)),
+        "minTrustScore": float(raw.get("minTrustScore", 0.0) or 0.0),
+        "proofReq": _cleanList(raw.get("proofReq", [])),
+        "refundPolicy": str(raw.get("refundPolicy", "") or ""),
+        "meta": raw.get("meta", {}) if isinstance(raw.get("meta"), dict) else {},
+    }
+
+
+def _scope(value: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "scopeId": str(value.get("scopeId", "") or ""),
+        "actions": _cleanList(value.get("actions", [])),
+        "resources": _cleanList(value.get("resources", [])),
+        "expiresAt": str(value.get("expiresAt", "") or ""),
+        "tokenRef": str(value.get("tokenRef", "") or ""),
+    }
+
+
+def _credentialRefs(value: Any) -> list[dict[str, str]]:
+    refs: list[dict[str, str]] = []
+    if not isinstance(value, list):
+        return refs
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        ref = str(item.get("ref", item.get("tokenRef", item.get("secretRef", item.get("env", "")))) or "")
+        if not ref:
+            continue
+        refs.append(
+            {
+                "ref": ref,
+                "kind": str(item.get("kind", item.get("type", "secretRef")) or "secretRef"),
+                "resource": str(item.get("resource", "") or ""),
+                "expiresAt": str(item.get("expiresAt", "") or ""),
+            }
+        )
+    return refs
+
+
+def _callback(value: Any) -> dict[str, str]:
+    raw = value if isinstance(value, dict) else {}
+    return {
+        "url": str(raw.get("url", raw.get("endpoint", "")) or ""),
+        "eventType": str(raw.get("eventType", "") or ""),
+        "stateRef": str(raw.get("stateRef", "") or ""),
+    }
+
+
+def _hasRawSecret(value: Any) -> bool:
+    if not isinstance(value, dict):
+        return False
+    for key, item in value.items():
+        if key in SECRET_KEYS and str(item or "").strip():
+            return True
+    return False
+
+
+def _hasScope(record: dict[str, Any], *, action: str, resource: str = "") -> bool:
+    for scope in record.get("scopes", []):
+        if action not in scope.get("actions", []):
+            continue
+        resources = scope.get("resources", [])
+        if not resource or "*" in resources or resource in resources:
+            return True
+    return False
+
+
+def _cleanList(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    deduped = []
+    for item in value:
+        clean = str(item or "").strip()
+        if clean and clean not in deduped:
+            deduped.append(clean)
+    return deduped
+
+
+def _kind(value: Any) -> str:
+    kind = str(value or "api")
+    return kind if kind in CONNECTOR_KINDS else kind
+
+
+def _status(value: Any) -> str:
+    status = str(value or "active")
+    return status if status in CONNECTOR_STATUSES else "active"
+
+
+def _connectionSessionStatus(value: Any) -> str:
+    status = str(value or "active")
+    return status if status in CONNECTION_SESSION_STATUSES else "active"
+
+
+def _connectionSessionMode(value: Any) -> str:
+    mode = str(value or "clientHostedAdapter")
+    return mode if mode in CONNECTION_SESSION_MODES else "clientHostedAdapter"
+
+
+def _sessionId(payload: dict[str, Any], now: int) -> str:
+    base = {k: v for k, v in payload.items() if k != "sessionId"}
+    base["createdAt"] = now
+    digest = hashlib.sha256(json.dumps(base, ensure_ascii=True, sort_keys=True, default=str).encode("utf-8")).hexdigest()
+    return "bridgeSess_" + digest[:24]
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))

picux/storage/envelopes.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import copy
+import time
+from typing import Any
+
+
+ENVELOPE_STATUSES = {"queued", "delivered", "acknowledged", "failed", "canceled"}
+
+
+class EnvelopeBook:
+    """A2A envelope storage with optional durable backing."""
+
+    def __init__(self, *, backing: Any | None = None) -> None:
+        self.backing = backing
+        self._records: dict[str, dict[str, Any]] = {}
+
+    def saveEnvelope(self, envelope: dict[str, Any], *, status: str = "queued") -> dict[str, Any]:
+        msgId = str(envelope.get("msgId", "") or "")
+        if not msgId:
+            return {"ok": False, "error": "missing:msgId"}
+        current = self.getEnvelope(msgId)
+        now = int(time.time())
+        createdAt = current.get("record", {}).get("createdAt", now) if current.get("ok") else now
+        record = _recordFromEnvelope(envelope, status=status, createdAt=createdAt, updatedAt=now)
+        self._saveRecord(record)
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def getEnvelope(self, msgId: str) -> dict[str, Any]:
+        msgId = str(msgId or "")
+        record = self._records.get(msgId)
+        if record is None and self._backingEnabled() and hasattr(self.backing, "fetchEnvelope"):
+            record = self.backing.fetchEnvelope(msgId)
+            if record:
+                self._records[msgId] = copy.deepcopy(record)
+        if not record:
+            return {"ok": False, "error": "envelopeNotFound", "msgId": msgId}
+        return {"ok": True, "record": copy.deepcopy(record)}
+
+    def listEnvelopes(self, filters: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._loadBacking()
+        filters = filters or {}
+        status = str(filters.get("status", "") or "")
+        fromAgent = str(filters.get("fromAgent", "") or "")
+        toAgent = str(filters.get("toAgent", "") or "")
+        traceId = str(filters.get("traceId", "") or "")
+        taskId = str(filters.get("taskId", "") or "")
+        records = list(self._records.values())
+        if status:
+            records = [record for record in records if record.get("status") == status]
+        if fromAgent:
+            records = [record for record in records if record.get("fromAgent") == fromAgent]
+        if toAgent:
+            records = [record for record in records if record.get("toAgent") == toAgent]
+        if traceId:
+            records = [record for record in records if record.get("traceId") == traceId]
+        if taskId:
+            records = [record for record in records if record.get("taskId") == taskId]
+        records.sort(
+            key=lambda item: (int(item.get("createdAt", 0) or 0), str(item.get("msgId", ""))),
+            reverse=True,
+        )
+        limit = _limit(filters.get("limit", 100))
+        return {
+            "ok": True,
+            "envelopes": [copy.deepcopy(record) for record in records[:limit]],
+            "count": min(len(records), limit),
+        }
+
+    def updateEnvelope(self, msgId: str, updates: dict[str, Any]) -> dict[str, Any]:
+        current = self.getEnvelope(msgId)
+        if not current.get("ok"):
+            return current
+        record = current["record"]
+        delivery = record.get("delivery", {}) if isinstance(record.get("delivery"), dict) else {}
+        if isinstance(updates.get("delivery"), dict):
+            delivery = copy.deepcopy(updates["delivery"])
+        merged = {
+            **record,
+            "status": _status(updates.get("status", record.get("status", "queued"))),
+            "delivery": delivery,
+            "errorMsg": str(updates.get("errorMsg", record.get("errorMsg", "")) or ""),
+            "updatedAt": int(updates.get("updatedAt", int(time.time())) or int(time.time())),
+        }
+        self._saveRecord(merged)
+        return {"ok": True, "record": copy.deepcopy(merged)}
+
+    def _saveRecord(self, record: dict[str, Any]) -> None:
+        msgId = str(record.get("msgId", "") or "")
+        if not msgId:
+            return
+        self._records[msgId] = copy.deepcopy(record)
+        if self._backingEnabled() and hasattr(self.backing, "upsertEnvelope"):
+            self.backing.upsertEnvelope(record)
+
+    def _loadBacking(self) -> None:
+        if self.backing is None or not self._backingEnabled() or not hasattr(self.backing, "listEnvelopes"):
+            return
+        for record in self.backing.listEnvelopes():
+            msgId = str(record.get("msgId", "") or "")
+            if msgId:
+                self._records[msgId] = copy.deepcopy(record)
+
+    def _backingEnabled(self) -> bool:
+        if self.backing is None:
+            return False
+        return bool(getattr(self.backing, "enabled", True))
+
+
+def _recordFromEnvelope(envelope: dict[str, Any], *, status: str, createdAt: int, updatedAt: int) -> dict[str, Any]:
+    task = envelope.get("task", {}) if isinstance(envelope.get("task"), dict) else {}
+    return {
+        "msgId": str(envelope.get("msgId", "") or ""),
+        "status": _status(status),
+        "fromAgent": str(envelope.get("fromAgent", "") or ""),
+        "toAgent": str(envelope.get("toAgent", "") or ""),
+        "traceId": str(envelope.get("traceId", "") or ""),
+        "taskId": str(task.get("taskId", "") or ""),
+        "envelope": copy.deepcopy(envelope),
+        "delivery": {},
+        "errorMsg": "",
+        "createdAt": int(createdAt or updatedAt),
+        "updatedAt": int(updatedAt or createdAt),
+    }
+
+
+def _status(value: Any) -> str:
+    status = str(value or "queued")
+    return status if status in ENVELOPE_STATUSES else "queued"
+
+
+def _limit(value: Any) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return 100
+    return max(1, min(parsed, 500))