f-layer 2.0.0__py3-none-any.whl

flayer/integrations/wire.py

@@ -0,0 +1,273 @@
+"""Bounded strict JSON codecs validate representations without dispatch or authorization."""
+
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from flayer.core.contracts import ParseIdentity, RequireTable, StackIdentity, ValidateFields
+from flayer.diagnostics.contracts import DiagnosticStatus
+
+from .contracts import (
+    MAX_CHECKS,
+    MAX_WIRE_BYTES,
+    METRIC_BOUNDS,
+    RESOURCE_STATUSES,
+    CheckEvidence,
+    DiagnosticEvidence,
+    IntegrationError,
+    IntegrationOperation,
+    IntegrationRequest,
+    IntegrationResult,
+    LifecycleEvidence,
+    Metric,
+    RequireIdentity,
+    ResourceCount,
+    StateEvidence,
+)
+
+MAX_JSON_DEPTH = 8
+MAX_JSON_VALUES = 4096
+ENVELOPE_FIELDS = frozenset({
+    "schema_version", "envelope", "identity", "request_id", "operation",
+})
+
+
+def _UniqueObject(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    """Reject duplicate fields at every object level without displaying their values."""
+
+    result: dict[str, object] = {}
+
+    for key, value in pairs:
+        if key in result:
+            raise IntegrationError("Integration JSON contains duplicate fields")
+
+        result[key] = value
+
+    return result
+
+
+def _RejectConstant(value: str) -> object:
+    """Reject nonstandard JSON numeric tokens without returning rejected text."""
+
+    raise IntegrationError("Integration JSON requires finite standard numbers")
+
+
+def _BoundStructure(value: object, depth: int, remaining: list[int]) -> None:
+    """Bound decoded nesting and total values before schema traversal."""
+
+    remaining[0] -= 1
+
+    if depth > MAX_JSON_DEPTH or remaining[0] < 0:
+        raise IntegrationError("Integration JSON exceeds its structural bounds")
+
+    if isinstance(value, dict):
+        for item in value.values():
+            _BoundStructure(item, depth + 1, remaining)
+
+    elif isinstance(value, list):
+        for item in value:
+            _BoundStructure(item, depth + 1, remaining)
+
+
+def _Decode(payload: str) -> object:
+    """Read only bounded UTF-8 JSON strings and sanitize every decoding error."""
+
+    try:
+        if not isinstance(payload, str) or len(payload) > MAX_WIRE_BYTES:
+            raise IntegrationError("Integration JSON exceeds its byte limit")
+
+        if len(payload.encode("utf-8")) > MAX_WIRE_BYTES:
+            raise IntegrationError("Integration JSON exceeds its byte limit")
+
+        decoded: object = json.loads(
+            payload, object_pairs_hook=_UniqueObject, parse_constant=_RejectConstant,
+        )
+        _BoundStructure(decoded, 0, [MAX_JSON_VALUES])
+
+        return decoded
+
+    except (ValueError, RecursionError, UnicodeError):
+        raise IntegrationError("Unable to parse a valid bounded integration envelope") from None
+
+
+def _Request(value: object, expected_identity: StackIdentity, envelope: str) -> IntegrationRequest:
+    """Bind decoded metadata to caller context with an exact envelope schema."""
+
+    table = RequireTable(value, "integration envelope")
+    extra_fields = frozenset({"evidence"}) if envelope == "result" else frozenset()
+    ValidateFields(table, ENVELOPE_FIELDS | extra_fields, frozenset(), "integration envelope")
+
+    if table["envelope"] != envelope:
+        raise IntegrationError("Integration envelope kind is unsupported")
+
+    identity = ParseIdentity(table["identity"])
+    RequireIdentity(identity, expected_identity)
+    request_id = table["request_id"]
+    operation = table["operation"]
+
+    if not isinstance(request_id, str) or not isinstance(operation, str):
+        raise IntegrationError("Integration correlation and operation require strings")
+
+    return IntegrationRequest(
+        identity, request_id, IntegrationOperation(operation), cast(int, table["schema_version"]),
+    )
+
+
+def ParseRequest(payload: str, expected_identity: StackIdentity) -> IntegrationRequest:
+    """Validate untrusted read-only intent without invoking any operation or permission check."""
+
+    try:
+        return _Request(_Decode(payload), expected_identity, "request")
+
+    except ValueError:
+        raise IntegrationError("Unable to parse a valid owned integration request") from None
+
+
+def _Array(value: object, limit: int) -> list[object]:
+    """Require bounded JSON arrays rather than accepting iterable or coerced values."""
+
+    if not isinstance(value, list) or len(value) > limit:
+        raise IntegrationError("Integration evidence requires a bounded array")
+
+    return value
+
+
+def _ParseDiagnostic(value: object) -> DiagnosticEvidence:
+    """Validate allowlisted checks and a severity summary consistent with their outcomes."""
+
+    table = RequireTable(value, "diagnostic evidence")
+    ValidateFields(table, frozenset({"status", "checks"}), frozenset(), "diagnostic evidence")
+    checks: list[CheckEvidence] = []
+
+    for item in _Array(table["checks"], MAX_CHECKS):
+        check = RequireTable(item, "check evidence")
+        ValidateFields(check, frozenset({"status", "metrics"}), frozenset(), "check evidence")
+        metrics = RequireTable(check["metrics"], "check metrics")
+        ValidateFields(metrics, frozenset(), frozenset(METRIC_BOUNDS), "check metrics")
+        checks.append(CheckEvidence(DiagnosticStatus(check["status"]), tuple(
+            Metric(name, cast(int | float | None, metric))
+            for name, metric in sorted(metrics.items())
+        )))
+
+    evidence = DiagnosticEvidence(tuple(checks))
+
+    if table["status"] != evidence.Status.value:
+        raise IntegrationError("Integration diagnostic summary does not match its checks")
+
+    return evidence
+
+
+def _ParseLifecycle(value: object) -> LifecycleEvidence:
+    """Decode only stable lifecycle outcomes and bounded observation category counts."""
+
+    table = RequireTable(value, "lifecycle evidence")
+    ValidateFields(table, frozenset({"action", "status", "recovery_required", "resources"}),
+                   frozenset(), "lifecycle evidence")
+    resources: list[ResourceCount] = []
+
+    for item in _Array(table["resources"], len(RESOURCE_STATUSES)):
+        resource = RequireTable(item, "resource count")
+        ValidateFields(resource, frozenset({"status", "count"}), frozenset(), "resource count")
+        resources.append(ResourceCount(cast(str, resource["status"]), cast(int, resource["count"])))
+
+    return LifecycleEvidence(
+        cast(str, table["action"]), cast(str, table["status"]),
+        cast(bool, table["recovery_required"]), tuple(resources),
+    )
+
+
+def ParseResult(payload: str, expected_request: IntegrationRequest) -> IntegrationResult:
+    """Bind an untrusted representation to its request without asserting authenticity."""
+
+    try:
+        if not isinstance(expected_request, IntegrationRequest):
+            raise IntegrationError("Integration result requires an originating request")
+
+        value = _Decode(payload)
+        request = _Request(value, expected_request.identity, "result")
+
+        if request != expected_request:
+            raise IntegrationError("Integration result does not match the originating request")
+
+        table = RequireTable(value, "integration result")
+
+        if request.operation is IntegrationOperation.STATE:
+            state = RequireTable(table["evidence"], "state evidence")
+            ValidateFields(state, frozenset({"resource_count"}), frozenset(), "state evidence")
+
+            return IntegrationResult(request, StateEvidence(cast(int, state["resource_count"])))
+
+        if request.operation is IntegrationOperation.LIFECYCLE_REPORT:
+            return IntegrationResult(request, _ParseLifecycle(table["evidence"]))
+
+        return IntegrationResult(request, _ParseDiagnostic(table["evidence"]))
+
+    except (ValueError, TypeError):
+        raise IntegrationError("Unable to parse a valid correlated integration result") from None
+
+
+def _Metadata(request: IntegrationRequest, envelope: str) -> dict[str, object]:
+    """Represent validated non-secret routing metadata without consumer-specific fields."""
+
+    return {
+        "schema_version": request.schema_version, "envelope": envelope,
+        "identity": {
+            "project": request.identity.project, "stack": request.identity.stack,
+            "provider": request.identity.provider, "scope_id": request.identity.scope_id,
+            "owner_id": request.identity.owner_id,
+        },
+        "request_id": request.request_id,
+        "operation": request.operation.value,
+    }
+
+
+def _Encode(value: dict[str, object]) -> str:
+    """Produce deterministic standard JSON within the same byte limit as parsing."""
+
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+    if len(payload.encode("utf-8")) > MAX_WIRE_BYTES:
+        raise IntegrationError("Serialized integration envelope exceeds its byte limit")
+
+    return payload
+
+
+def SerializeRequest(request: IntegrationRequest) -> str:
+    """Serialize validated observation intent without resolving targets or credentials."""
+
+    if not isinstance(request, IntegrationRequest):
+        raise IntegrationError("Integration serialization requires a validated request")
+
+    return _Encode(_Metadata(request, "request"))
+
+
+def SerializeResult(result: IntegrationResult) -> str:
+    """Serialize only explicitly allowed evidence, never source objects or raw adapter data."""
+
+    if not isinstance(result, IntegrationResult):
+        raise IntegrationError("Integration serialization requires a validated result")
+
+    value = _Metadata(result.request, "result")
+    evidence = result.evidence
+
+    if isinstance(evidence, DiagnosticEvidence):
+        value["evidence"] = {
+            "status": evidence.Status.value,
+            "checks": [{"status": check.status.value,
+                        "metrics": {metric.name: metric.value for metric in check.metrics}}
+                       for check in evidence.checks],
+        }
+
+    elif isinstance(evidence, StateEvidence):
+        value["evidence"] = {"resource_count": evidence.resource_count}
+
+    else:
+        value["evidence"] = {
+            "action": evidence.action, "status": evidence.status,
+            "recovery_required": evidence.recovery_required,
+            "resources": [{"status": resource.status, "count": resource.count}
+                          for resource in evidence.resources],
+        }
+
+    return _Encode(value)

flayer/profiles/__init__.py

@@ -0,0 +1,33 @@
+"""Explicit deployment profiles and owned generated artifacts."""
+
+from .artifacts import (
+    Artifact,
+    ArtifactBundle,
+    ArtifactError,
+    BuildDeviceBundle,
+    RemoveArtifactBundle,
+    WriteArtifactBundle,
+)
+from .gateway import (
+    BuildServerBundle,
+    BuildSshDeviceBundle,
+    CompileGateway,
+    GatewayDevice,
+    GatewayError,
+    GatewayPlan,
+    GatewayPort,
+    GatewayProfile,
+    GatewayTarget,
+    GatewayTransport,
+    LoadGatewayProfile,
+    ParseGatewayProfile,
+    RenderPlan,
+)
+
+__all__ = [
+    "Artifact", "ArtifactBundle", "ArtifactError", "BuildDeviceBundle", "BuildServerBundle",
+    "BuildSshDeviceBundle", "GatewayDevice", "GatewayTarget", "GatewayTransport",
+    "CompileGateway", "GatewayError", "GatewayPlan", "GatewayPort", "GatewayProfile",
+    "LoadGatewayProfile", "ParseGatewayProfile", "RemoveArtifactBundle", "RenderPlan",
+    "WriteArtifactBundle",
+]

flayer/profiles/_amnezia_export.py

@@ -0,0 +1,176 @@
+"""Encode private AmneziaVPN connection profiles and native scanner QR frames."""
+
+from __future__ import annotations
+
+import base64
+import configparser
+import importlib
+import io
+import ipaddress
+import json
+import struct
+import zlib
+
+from flayer.profiles.artifacts import Artifact
+from flayer.profiles.vpn import VpnError
+
+QR_CHUNK_BYTES = 850
+QR_MAGIC = 1984
+
+
+def BuildAmneziaArtifacts(
+    client: bytes, host: str, device_id: str, dns_servers: tuple[str, ...],
+    *, qr: bool = True,
+) -> tuple[Artifact, ...]:
+    """Wrap one exact Xray policy without server keys or administration credentials."""
+
+    profile: dict[str, object] = {
+        "containers": [{"container": "amnezia-xray", "xray": {
+            "last_config": client.decode("utf-8"), "isThirdPartyConfig": True,
+        }}],
+        "defaultContainer": "amnezia-xray", "hostName": host,
+        "description": f"F-Layer VLESS {device_id}",
+        "dns1": dns_servers[0], "dns2": dns_servers[1] if len(dns_servers) > 1 else dns_servers[0],
+    }
+
+    return _EncodeProfile(profile, qr=qr)
+
+
+def _EncodeProfile(profile: dict[str, object], *, qr: bool) -> tuple[Artifact, ...]:
+    """Encode one native profile and optionally its scanner frames without network access."""
+
+    content = json.dumps(profile, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    # Qt qCompress prefixes the zlib stream with its uncompressed size in network byte order.
+    compressed = struct.pack(">I", len(content)) + zlib.compress(content, level=8)
+    encoded = base64.urlsafe_b64encode(compressed).rstrip(b"=")
+    artifacts = (Artifact("amnezia.vpn", b"vpn://" + encoded + b"\n"),)
+
+    return artifacts + (_QrArtifacts(compressed) if qr else ())
+
+
+def _QrArtifacts(compressed: bytes) -> tuple[Artifact, ...]:
+    """Render numbered qCompress/QDataStream frames understood by the native scanner."""
+
+    try:
+        segno = importlib.import_module("segno")
+
+    except ImportError:
+        raise VpnError("Install the f-layer[vpn] extra before exporting AmneziaVPN QR codes") from None
+
+    artifacts: list[Artifact] = []
+    chunks = [compressed[index:index + QR_CHUNK_BYTES]
+              for index in range(0, len(compressed), QR_CHUNK_BYTES)]
+
+    if len(chunks) > 255:
+        raise VpnError("AmneziaVPN profile exceeds the native QR frame limit")
+
+    for index, chunk in enumerate(chunks):
+        # QDataStream: qint16 magic, quint8 count/index, then a length-prefixed QByteArray.
+        frame = struct.pack(">hBBI", QR_MAGIC, len(chunks), index, len(chunk)) + chunk
+        payload = base64.urlsafe_b64encode(frame).rstrip(b"=").decode("ascii")
+        output = io.BytesIO()
+        segno.make_qr(payload, error="L", boost_error=False).save(
+            output, kind="svg", scale=5, border=4, light="white",
+        )
+        artifacts.append(Artifact(f"amnezia-qr-{index + 1:02d}.svg", output.getvalue()))
+
+    return tuple(artifacts)
+
+
+def BuildAmneziaQrArtifacts(connection: bytes) -> tuple[Artifact, ...]:
+    """Render scanner frames from an existing connection key without changing its profile."""
+
+    try:
+        encoded = connection.strip().removeprefix(b"vpn://")
+
+        if not connection.startswith(b"vpn://") or not 1 <= len(encoded) <= 1048576:
+            raise ValueError
+
+        compressed = base64.b64decode(encoded + b"=" * (-len(encoded) % 4), altchars=b"-_", validate=True)
+
+        if base64.urlsafe_b64encode(compressed).rstrip(b"=") != encoded:
+            raise ValueError
+
+        return _QrArtifacts(compressed)
+
+    except ValueError:
+        raise VpnError("Existing AmneziaVPN connection key is invalid") from None
+
+
+class _AwgConfigParser(configparser.ConfigParser):
+    """Preserve case-sensitive AWG protocol keys rather than ConfigParser normalization."""
+
+    def optionxform(self, optionstr: str) -> str:
+        """Honor the parser callback while retaining the external configuration contract."""
+
+        return optionstr
+
+
+def BuildAmneziaWgArtifacts(client: bytes, device_id: str, *, qr: bool = False) -> tuple[Artifact, ...]:
+    """Wrap existing AWG bytes and structured 3.1 fields without issuing or rotating keys."""
+
+    from flayer.profiles.amneziawg import AmneziaWgSettings, _Key, _PublicKey
+    from flayer.profiles.vpn import VpnEndpoint, VpnRoutes
+
+    obfuscation = (
+        "Jc", "Jmin", "Jmax", "S1", "S2", "S3", "S4", "H1", "H2", "H3", "H4",
+        "I1", "I2", "I3", "I4", "I5", "HeaderProtectionKey", "ContentPaddingAddition",
+        "RekeyAfterTime", "RekeyTimeout", "RejectAfterTime", "KeepaliveTimeout",
+        "MaxHandshakeAttempts", "RandomTrailers", "DisableCookies",
+    )
+
+    try:
+        parser = _AwgConfigParser(interpolation=None, strict=True)
+        parser.read_string(client.decode("utf-8"))
+
+        if set(parser.sections()) != {"Interface", "Peer"} or parser.defaults():
+            raise ValueError
+
+        interface, peer = parser["Interface"], parser["Peer"]
+        required = {"PrivateKey", "Address", "MTU", "DNS"}
+
+        if not required <= set(interface) or set(interface) - required - set(obfuscation):
+            raise ValueError
+
+        if set(peer) != {"PublicKey", "Endpoint", "AllowedIPs", "PersistentKeepalive"}:
+            raise ValueError
+
+        host, port = peer["Endpoint"].rsplit(":", 1)
+        endpoint = VpnEndpoint(host, int(port))
+        routes = tuple(item.strip() for item in peer["AllowedIPs"].split(","))
+        dns_servers = tuple(item.strip() for item in interface["DNS"].split(","))
+        VpnRoutes("full" if routes == ("0.0.0.0/0",) else "split", routes, dns_servers, "disabled")
+        AmneziaWgSettings(mtu=int(interface["MTU"]))
+        address = ipaddress.IPv4Interface(interface["Address"])
+
+        if address.network.prefixlen != 32 or not address.ip.is_private or len(dns_servers) > 2:
+            raise ValueError
+
+        if not 0 <= int(peer["PersistentKeepalive"]) <= 65535:
+            raise ValueError
+
+        private_key = _Key(interface["PrivateKey"])
+        public_key = _PublicKey(private_key)
+        server_key = _Key(peer["PublicKey"])
+        fields: dict[str, object] = {
+            "config": client.decode("utf-8"), "hostName": endpoint.host, "port": endpoint.port,
+            "client_ip": str(address.ip),
+            "client_priv_key": private_key, "client_pub_key": public_key, "clientId": public_key,
+            "server_pub_key": server_key, "allowed_ips": list(routes), "mtu": interface["MTU"],
+            "persistent_keep_alive": peer["PersistentKeepalive"],
+        }
+        fields.update({key: interface[key] for key in obfuscation if key in interface})
+        last_config = json.dumps(fields, ensure_ascii=False, separators=(",", ":"))
+        profile: dict[str, object] = {
+            "containers": [{"container": "amnezia-awg", "awg": {
+                "last_config": last_config, "isThirdPartyConfig": True,
+            }}],
+            "defaultContainer": "amnezia-awg", "hostName": host,
+            "description": f"F-Layer AmneziaWG {device_id}",
+            "dns1": dns_servers[0], "dns2": dns_servers[1] if len(dns_servers) > 1 else dns_servers[0],
+        }
+
+    except (ValueError, KeyError, configparser.Error, UnicodeError):
+        raise VpnError("Existing AmneziaWG device configuration is invalid or unsupported") from None
+
+    return _EncodeProfile(profile, qr=qr)