f-layer 2.0.1__py3-none-any.whl

flayer/__main__.py

@@ -0,0 +1,247 @@
+"""Explicit diagnostics and opt-in owned lifecycle CLI without implicit cloud discovery."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+from dataclasses import asdict
+from typing import NoReturn
+
+from .diagnostics import (
+    BenchmarkLimits,
+    CheckResult,
+    DiagnosticReport,
+    DiagnosticStatus,
+    ProbeEndpoint,
+    ProviderStatus,
+    RenderJson,
+    RenderText,
+    RunBenchmark,
+    RuntimeChecks,
+)
+
+
+class DiagnosticArgumentParser(argparse.ArgumentParser):
+    """Suppress raw invalid argument values that may contain private endpoint material."""
+
+    def error(self, message: str) -> NoReturn:
+        """Preserve argparse's exit contract while keeping untrusted argument text private."""
+
+        self.exit(2, f"{self.prog}: error: invalid command arguments\n")
+
+
+def Parser() -> argparse.ArgumentParser:
+    """Build an offline help surface and bounded command options."""
+
+    parser = DiagnosticArgumentParser(prog="python -m flayer", description="F-Layer diagnostics and owned lifecycle")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    for command in ("status", "check", "health", "benchmark"):
+        child = commands.add_parser(command)
+        child.add_argument("--format", choices=("text", "json"), default="text")
+
+        if command in ("health", "benchmark"):
+            child.add_argument("--endpoint", help="Explicit HTTP(S) endpoint without credentials")
+            child.add_argument("--timeout", type=float, default=3.0, metavar="SECONDS")
+
+        if command == "benchmark":
+            child.add_argument("--count", type=int, default=3)
+            child.add_argument("--bytes", type=int, default=64 * 1024, dest="byte_limit")
+
+    lifecycle = commands.add_parser("lifecycle", help="Explicit owned stack lifecycle")
+    actions = lifecycle.add_subparsers(dest="action", required=True)
+
+    for action in ("create", "status", "destroy", "recover"):
+        child = actions.add_parser(action)
+        child.add_argument("--config", required=True, help="Explicit lifecycle plan TOML path")
+        child.add_argument("--state", required=True, help="Explicit owned snapshot path")
+        child.add_argument("--yc-profile", required=True, help="Explicit preauthenticated yc profile")
+        child.add_argument("--format", choices=("text", "json"), default="text")
+
+        if action != "status":
+            child.add_argument("--allow-mutation", action="store_true")
+            child.add_argument("--scope-confirm", required=True, help="Repeat the exact folder ID")
+
+        if action == "recover":
+            child.add_argument("--rollback", action="store_true")
+
+    project = commands.add_parser("project", help="Create a private installable VPN project")
+    project_actions = project.add_subparsers(dest="action", required=True)
+    initialize = project_actions.add_parser("init", help="Create an editable project and administration key")
+    initialize.add_argument("directory")
+
+    vpn = commands.add_parser("vpn", help="Prepare and manage a two-protocol VPN project")
+    vpn_actions = vpn.add_subparsers(dest="action", required=True)
+
+    for action in ("prepare", "deploy", "status", "destroy", "recover"):
+        child = vpn_actions.add_parser(action)
+        child.add_argument("--project", required=True, help="Private project directory")
+        child.add_argument("--format", choices=("text", "json"), default="text")
+
+        if action in {"deploy", "destroy", "recover"}:
+            child.add_argument("--allow-mutation", action="store_true")
+            child.add_argument("--scope-confirm", required=True, help="Repeat the exact cloud folder ID")
+
+        if action == "recover":
+            child.add_argument("--rollback", action="store_true")
+
+    export = vpn_actions.add_parser("export", help="Export existing device files without cloud access")
+    export.add_argument("--project", required=True, help="Private project directory")
+    export.add_argument("--device", required=True, help="One declared device ID")
+    export.add_argument("--protocol", required=True, choices=("amneziawg", "vless-reality"))
+    export.add_argument("--output", required=True, help="Separate private export root")
+    export.add_argument("--qr", action="store_true", help="Include numbered native AmneziaVPN QR SVGs")
+    export.add_argument("--format", choices=("text", "json"), default="text")
+
+    return parser
+
+
+def _Lifecycle(args: argparse.Namespace) -> int:
+    """Require concrete scope opt-in before constructing a mutating provider adapter."""
+
+    from .core.lifecycle import LifecycleEngine, LifecycleError, LoadDeploymentPlan
+    from .core.state import StateError
+    from .providers.contracts import ProviderError
+    from .providers.yandex import YandexCloudSettings
+    from .providers.yandex_lifecycle import YandexLifecycleProvider
+
+    try:
+        plan = LoadDeploymentPlan(args.config)
+
+        if plan.identity.provider != "yandex-cloud":
+            raise LifecycleError("CLI lifecycle provider is unsupported")
+
+        if args.action != "status" and (
+            not args.allow_mutation or args.scope_confirm != plan.identity.scope_id
+        ):
+            raise LifecycleError("Mutation requires explicit opt-in and exact scope confirmation")
+
+        provider = YandexLifecycleProvider(YandexCloudSettings(
+            folder_id=plan.identity.scope_id, profile=args.yc_profile,
+        ))
+        engine = LifecycleEngine(plan, provider, args.state)
+
+        if args.action == "create":
+            report = engine.Create()
+
+        elif args.action == "status":
+            report = engine.Status()
+
+        elif args.action == "destroy":
+            report = engine.Destroy()
+
+        else:
+            report = engine.Recover(rollback=args.rollback)
+
+    except (LifecycleError, StateError, ProviderError, ValueError):
+        payload = {"action": args.action, "status": "failed", "recovery_required": True}
+        print(json.dumps(payload) if args.format == "json" else "Lifecycle operation blocked or failed")
+
+        return 2
+
+    print(json.dumps(asdict(report), sort_keys=True) if args.format == "json" else
+          f"Lifecycle {report.action}: {report.status}; resources={len(report.resources)}; "
+          f"recovery_required={str(report.recovery_required).lower()}")
+
+    return report.ExitCode()
+
+
+def _VpnProject(args: argparse.Namespace) -> int:
+    """Dispatch local project creation or explicit VPN operations without revealing private data."""
+
+    from .core.contracts import ContractError
+    from .profiles.vpn import VpnError
+    from .providers.contracts import ProviderError
+    from .vpn_project import InitializeVpnProject, LoadVpnProject, RunVpnProject
+
+    try:
+        if args.command == "project":
+            InitializeVpnProject(args.directory)
+            print("Private project created. Edit project.toml, then run flayer vpn prepare --project DIRECTORY.")
+
+            return 0
+
+        project = LoadVpnProject(args.project)
+
+        if args.action == "export":
+            from .vpn_export import ExportVpnDevice
+
+            report = ExportVpnDevice(project, args.device, args.protocol, args.output, qr=args.qr)
+
+        else:
+            report = RunVpnProject(
+                project, args.action,
+                allow_mutation=getattr(args, "allow_mutation", False),
+                scope_confirm=getattr(args, "scope_confirm", ""),
+                rollback=getattr(args, "rollback", False),
+            )
+
+    except (ContractError, ProviderError, OSError) as error:
+        message = str(error) if isinstance(error, VpnError) else (
+            "Device export failed. Verify existing source manifests and private output permissions; source files were not changed."
+            if args.action == "export" else
+            "VPN operation failed. Check private artifact ownership, cloud access, and retained state before retrying."
+        )
+        payload = {"action": args.action, "status": "failed", "message": message,
+                   "recovery_required": args.action in {"deploy", "destroy", "recover"}}
+        print(json.dumps(payload) if getattr(args, "format", "text") == "json" else message)
+
+        return 2
+
+    print(json.dumps(asdict(report), sort_keys=True) if args.format == "json" else
+          f"VPN {report.action}: {report.status}; cloud={report.cloud_status}; guest={report.guest_status}; "
+          f"connectivity={report.connectivity_status}. {report.details}")
+
+    for export in report.client_exports if args.format == "text" else ():
+        print(f"Client files: {export}")
+
+    return report.ExitCode()
+
+
+def Main(arguments: Sequence[str] | None = None) -> int:
+    """Run explicit diagnostics or authorized lifecycle actions and return their outcome."""
+
+    args = Parser().parse_args(arguments)
+
+    if args.command in {"project", "vpn"}:
+        return _VpnProject(args)
+
+    if args.command == "lifecycle":
+        return _Lifecycle(args)
+
+    try:
+        if args.command == "status":
+            checks = (*RuntimeChecks(), ProviderStatus())
+
+        elif args.command == "check":
+            checks = RuntimeChecks()
+
+        elif not args.endpoint:
+            checks = (CheckResult(
+                "endpoint", DiagnosticStatus.UNSUPPORTED, "An explicit endpoint is required"
+            ),)
+
+        elif args.command == "health":
+            checks = (ProbeEndpoint(args.endpoint, args.timeout),)
+
+        else:
+            limits = BenchmarkLimits(args.timeout, args.count, args.byte_limit)
+            checks = RunBenchmark(args.endpoint, limits)
+
+    except ValueError:
+        report = DiagnosticReport(args.command, (CheckResult(
+            "input", DiagnosticStatus.FAILED, "Invalid endpoint or diagnostic limits"
+        ),))
+        print(RenderJson(report) if args.format == "json" else RenderText(report))
+
+        return 2
+
+    report = DiagnosticReport(args.command, checks)
+    print(RenderJson(report) if args.format == "json" else RenderText(report))
+
+    return report.ExitCode()
+
+
+if __name__ == "__main__":
+    raise SystemExit(Main())

flayer/_vpn_guest.py

@@ -0,0 +1,130 @@
+"""Receive private VPN installation payloads over an already authenticated root SSH channel."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+MAX_REQUEST_BYTES = 4 * 1024 * 1024
+_FILENAME = re.compile(r"[a-z][a-z0-9-]{0,62}\.[a-z0-9]{1,12}\Z")
+
+
+class GuestInstallError(ValueError):
+    """Carry only an allowlisted transport and phase, never raw installer diagnostics."""
+
+    def __init__(self, transport: str, phase: str) -> None:
+        """Record fixed internal operation labels for a sanitized failure receipt."""
+
+        super().__init__("Guest installation failed")
+        self.transport = transport
+        self.phase = phase
+
+
+def DecodeRequest(content: bytes) -> tuple[tuple[str, dict[str, bytes]], ...]:
+    """Validate all private data before creating any guest files or running an installer."""
+
+    if not 1 <= len(content) <= MAX_REQUEST_BYTES:
+        raise ValueError("Invalid guest request size")
+
+    request = json.loads(content)
+
+    if not isinstance(request, dict) or set(request) != {"bundles"} or not isinstance(request["bundles"], list) or not 1 <= len(request["bundles"]) <= 2:
+        raise ValueError("Invalid guest request")
+
+    result: list[tuple[str, dict[str, bytes]]] = []
+
+    for bundle in request["bundles"]:
+        if (
+            not isinstance(bundle, dict) or set(bundle) != {"transport", "files"}
+            or bundle["transport"] not in {"amneziawg", "vless-reality"}
+            or not isinstance(bundle["files"], dict) or not 1 <= len(bundle["files"]) <= 8
+        ):
+            raise ValueError("Invalid transport bundle")
+
+        files = {}
+
+        for name, encoded in bundle["files"].items():
+            if not isinstance(name, str) or _FILENAME.fullmatch(name) is None or not isinstance(encoded, str):
+                raise ValueError("Invalid transport filename")
+
+            decoded = base64.b64decode(encoded, validate=True)
+
+            if not 1 <= len(decoded) <= 1048576:
+                raise ValueError("Invalid transport file size")
+
+            files[name] = decoded
+
+        entrypoint = "install.sh" if bundle["transport"] == "amneziawg" else "install.py"
+
+        if entrypoint not in files or any(transport == bundle["transport"] for transport, _ in result):
+            raise ValueError("Invalid installer entrypoint or duplicate transport")
+
+        result.append((bundle["transport"], files))
+
+    return tuple(result)
+
+
+def Install(bundles: tuple[tuple[str, dict[str, bytes]], ...]) -> None:
+    """Use root-owned temporary directories and suppress potentially sensitive installer output."""
+
+    if os.geteuid() != 0:
+        raise ValueError("Root privileges are required")
+
+    for transport, files in bundles:
+        stage = Path(tempfile.mkdtemp(prefix="flayer-install-", dir="/var/tmp"))
+
+        phase = "stage"
+
+        try:
+            os.chmod(stage, 0o700)
+
+            for name, content in files.items():
+                descriptor = os.open(stage / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+
+                with os.fdopen(descriptor, "wb") as stream:
+                    stream.write(content)
+
+            command = ["/bin/bash", str(stage / "install.sh")] if transport == "amneziawg" else ["/usr/bin/python3", str(stage / "install.py")]
+            phase = "install"
+            subprocess.run(command, cwd=stage, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True, timeout=1800)
+            phase = "check"
+            subprocess.run(command + ["--check"], cwd=stage, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True, timeout=60)
+
+        except (OSError, subprocess.SubprocessError):
+            raise GuestInstallError(transport, phase) from None
+
+        finally:
+            shutil.rmtree(stage)
+
+
+def Main() -> int:
+    """Return only fixed status text, never request data or private installer diagnostics."""
+
+    try:
+        bundles = DecodeRequest(sys.stdin.buffer.read(MAX_REQUEST_BYTES + 1))
+        Install(bundles)
+
+    except GuestInstallError as error:
+        print(f"FLAYER_GUEST_FAILED {error.transport} {error.phase}")
+
+        return 1
+
+    except Exception:
+        print("F-Layer guest installation failed", file=sys.stderr)
+
+        return 1
+
+    print("FLAYER_GUEST_INSTALL_OK")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(Main())

flayer/core/__init__.py

@@ -0,0 +1 @@
+"""Provider-independent desired configuration and owned-state contracts."""

flayer/core/config.py

@@ -0,0 +1,198 @@
+"""Strict TOML desired-state loading without provider defaults or secret material."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contracts import (
+    SCHEMA_VERSION,
+    ContractError,
+    ParseIdentity,
+    RequireTable,
+    StackIdentity,
+    ValidateFields,
+    ValidateName,
+    ValidateSchemaVersion,
+)
+
+_ENVIRONMENT_NAME = re.compile(r"[A-Z_][A-Z0-9_]*")
+
+
+class ConfigError(ContractError):
+    """Desired configuration cannot be safely parsed or read."""
+
+
+@dataclass(frozen=True)
+class SecretReference:
+    """A named credential source; resolution belongs to an authentication adapter."""
+
+    name: str
+    source: str
+    reference: str
+
+    def __post_init__(self) -> None:
+        """Allow environment names and file paths, never inline credential values."""
+
+        ValidateName(self.name, "credentials.name")
+
+        if not isinstance(self.source, str) or self.source not in {"env", "file"}:
+            raise ContractError("credentials.source must be env or file")
+
+        if self.source == "env":
+            if (
+                not isinstance(self.reference, str)
+                or _ENVIRONMENT_NAME.fullmatch(self.reference) is None
+            ):
+                raise ContractError("credentials.reference must be an environment variable name")
+
+        elif (
+            not isinstance(self.reference, str)
+            or not self.reference.strip()
+            or self.reference != self.reference.strip()
+            or len(self.reference) > 4096
+            or any(ord(character) < 32 or ord(character) == 127 for character in self.reference)
+        ):
+            raise ContractError("credentials.reference must be a nonempty file path")
+
+
+@dataclass(frozen=True)
+class DesiredResource:
+    """Provider-independent logical resource identity before an external resource exists."""
+
+    logical_id: str
+    kind: str
+    name: str
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous logical identifiers and malformed names."""
+
+        ValidateName(self.logical_id, "resources.logical_id")
+        ValidateName(self.kind, "resources.kind")
+        ValidateName(self.name, "resources.name")
+
+
+@dataclass(frozen=True)
+class DesiredConfig:
+    """Immutable, validated desired intent without observed identifiers or credentials."""
+
+    identity: StackIdentity
+    profile: str
+    resources: tuple[DesiredResource, ...] = ()
+    credentials: tuple[SecretReference, ...] = ()
+    schema_version: int = SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        """Preserve model invariants when callers construct plans directly."""
+
+        ValidateSchemaVersion(self.schema_version)
+
+        if not isinstance(self.identity, StackIdentity):
+            raise ContractError("identity must be a StackIdentity")
+
+        ValidateName(self.profile, "profile")
+
+        if not isinstance(self.resources, tuple) or any(
+            not isinstance(resource, DesiredResource) for resource in self.resources
+        ):
+            raise ContractError("resources must be a tuple of DesiredResource values")
+
+        if len({resource.logical_id for resource in self.resources}) != len(self.resources):
+            raise ContractError("resources.logical_id values must be unique")
+
+        if not isinstance(self.credentials, tuple) or any(
+            not isinstance(credential, SecretReference) for credential in self.credentials
+        ):
+            raise ContractError("credentials must be a tuple of SecretReference values")
+
+        if len({credential.name for credential in self.credentials}) != len(self.credentials):
+            raise ContractError("credentials.name values must be unique")
+
+
+def _ParseResources(value: object) -> tuple[DesiredResource, ...]:
+    """Decode strictly typed logical resource tables."""
+
+    if not isinstance(value, list):
+        raise ContractError("resources must be an array of tables")
+
+    resources: list[DesiredResource] = []
+
+    for item in value:
+        table = RequireTable(item, "resources")
+        ValidateFields(table, frozenset({"logical_id", "kind", "name"}), frozenset(), "resources")
+        resources.append(
+            DesiredResource(
+                logical_id=ValidateName(table["logical_id"], "resources.logical_id"),
+                kind=ValidateName(table["kind"], "resources.kind"),
+                name=ValidateName(table["name"], "resources.name"),
+            )
+        )
+
+    return tuple(resources)
+
+
+def _ParseCredentials(value: object) -> tuple[SecretReference, ...]:
+    """Decode references without consulting the environment or reading credential files."""
+
+    if not isinstance(value, list):
+        raise ContractError("credentials must be an array of tables")
+
+    credentials: list[SecretReference] = []
+
+    for item in value:
+        table = RequireTable(item, "credentials")
+        ValidateFields(
+            table, frozenset({"name", "source", "reference"}), frozenset(), "credentials"
+        )
+
+        if not isinstance(table["source"], str) or not isinstance(table["reference"], str):
+            raise ContractError("credentials.source and reference must be strings")
+
+        credentials.append(
+            SecretReference(
+                name=ValidateName(table["name"], "credentials.name"),
+                source=table["source"],
+                reference=table["reference"],
+            )
+        )
+
+    return tuple(credentials)
+
+
+def ParseConfig(data: Mapping[str, object]) -> DesiredConfig:
+    """Validate decoded TOML; unknown fields and schema versions always fail closed."""
+
+    try:
+        ValidateFields(
+            data,
+            frozenset({"schema_version", "identity", "profile"}),
+            frozenset({"resources", "credentials"}),
+            "configuration",
+        )
+        ValidateSchemaVersion(data["schema_version"])
+
+        return DesiredConfig(
+            identity=ParseIdentity(data["identity"]),
+            profile=ValidateName(data["profile"], "profile"),
+            resources=_ParseResources(data.get("resources", [])),
+            credentials=_ParseCredentials(data.get("credentials", [])),
+        )
+
+    except ContractError as error:
+        raise ConfigError(str(error)) from error
+
+
+def LoadConfig(path: str | Path) -> DesiredConfig:
+    """Load an explicit TOML path with no implicit local defaults or environment overrides."""
+
+    try:
+        with Path(path).open("rb") as stream:
+            data = tomllib.load(stream)
+
+    except (OSError, ValueError, RecursionError) as error:
+        raise ConfigError("Unable to read a valid TOML configuration") from error
+
+    return ParseConfig(data)

flayer/core/contracts.py

@@ -0,0 +1,114 @@
+"""Validated identities shared by desired plans and persisted resource ownership."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+SCHEMA_VERSION = 1
+MANAGED_BY = "f-layer"
+IDENTITY_FIELDS = frozenset({"project", "stack", "provider", "scope_id", "owner_id"})
+_NAME_PATTERN = re.compile(r"[a-z][a-z0-9-]{0,62}")
+
+
+class ContractError(ValueError):
+    """An input violates a versioned core contract before any external operation."""
+
+
+def ValidateName(value: object, label: str) -> str:
+    """Require a bounded portable name without coercing invalid input types."""
+
+    if not isinstance(value, str) or _NAME_PATTERN.fullmatch(value) is None:
+        raise ContractError(f"{label} must be a lowercase name of 1..63 characters")
+
+    return value
+
+
+def ValidateIdentifier(value: object, label: str) -> str:
+    """Accept opaque provider identifiers without control characters or whitespace."""
+
+    if (
+        not isinstance(value, str)
+        or not 1 <= len(value) <= 256
+        or any(not 33 <= ord(character) <= 126 for character in value)
+    ):
+        raise ContractError(f"{label} must be a nonempty printable ASCII identifier")
+
+    return value
+
+
+def ValidateSchemaVersion(value: object) -> None:
+    """Reject unknown schema versions and booleans masquerading as integers."""
+
+    if type(value) is not int or value != SCHEMA_VERSION:
+        raise ContractError(f"schema_version must be the supported integer {SCHEMA_VERSION}")
+
+
+def ValidateFields(
+    data: Mapping[str, object], required: frozenset[str], optional: frozenset[str], label: str
+) -> None:
+    """Reject missing and unknown fields instead of silently accepting configuration typos."""
+
+    if not isinstance(data, Mapping):
+        raise ContractError(f"{label} must be a table")
+
+    if required - data.keys():
+        raise ContractError(f"{label} is missing required fields")
+
+    if data.keys() - required - optional:
+        raise ContractError(f"{label} contains unknown fields")
+
+
+def RequireTable(value: object, label: str) -> Mapping[str, object]:
+    """Require a string-keyed table at an untrusted decoding boundary."""
+
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ContractError(f"{label} must be a table")
+
+    return value
+
+
+@dataclass(frozen=True)
+class StackIdentity:
+    """Exact ownership boundary for one provider scope and one managed stack."""
+
+    project: str
+    stack: str
+    provider: str
+    scope_id: str
+    owner_id: str
+
+    def __post_init__(self) -> None:
+        """Validate direct construction as strictly as decoded configuration."""
+
+        ValidateName(self.project, "identity.project")
+        ValidateName(self.stack, "identity.stack")
+        ValidateName(self.provider, "identity.provider")
+        ValidateIdentifier(self.scope_id, "identity.scope_id")
+        ValidateName(self.owner_id, "identity.owner_id")
+
+    def OwnershipLabels(self) -> dict[str, str]:
+        """Return explicit labels for provider adapters to attach and verify."""
+
+        return {
+            "managed-by": MANAGED_BY,
+            "flayer-project": self.project,
+            "flayer-stack": self.stack,
+            "flayer-owner": self.owner_id,
+        }
+
+
+def ParseIdentity(value: object) -> StackIdentity:
+    """Decode a complete identity without defaulting missing ownership information."""
+
+    table = RequireTable(value, "identity")
+    ValidateFields(table, IDENTITY_FIELDS, frozenset(), "identity")
+
+    return StackIdentity(
+        project=ValidateName(table["project"], "identity.project"),
+        stack=ValidateName(table["stack"], "identity.stack"),
+        provider=ValidateName(table["provider"], "identity.provider"),
+        scope_id=ValidateIdentifier(table["scope_id"], "identity.scope_id"),
+        owner_id=ValidateName(table["owner_id"], "identity.owner_id"),
+    )