engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/local_api.py

@@ -0,0 +1,209 @@
+"""Historical Local Consumer API contract fixture; not an EP service.
+
+The current product's supported submission ingress is the Server HTTP JSON
+endpoint, installed CLI and Server-owned File Inbox.  This module retains the
+small read-only contract fixture needed by provenance and regression tests; it
+does not provide an install, LaunchAgent, lifecycle, repair or health surface.
+"""
+
+from __future__ import annotations
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+from pathlib import Path
+
+from .contracts.ep_consumer import (
+    ContractError,
+    ErrorCode,
+    ErrorEnvelope,
+    RequestEnvelope,
+    ResponseEnvelope,
+)
+from .ep_consumer_credentials import CredentialAuthority
+from .storage import open_storage
+
+# These labels are historical identities only.  They are deliberately not
+# component identifiers, lifecycle targets or installation defaults.
+HISTORICAL_LEGACY_LABEL = "com.djconnect.engineering-local-api"
+HISTORICAL_NEUTRAL_LABEL = "com.engineeringplatform.local-api"
+LOOPBACK_ADDRESS = "127.0.0.1"
+DEFAULT_PORT = 8766
+MAX_BODY_BYTES = 8192
+REQUEST_TIMEOUT_SECONDS = 15
+
+
+def valid_port(value: object) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 1024 <= value <= 65535:
+        raise ValueError("Local Consumer API port is invalid.")
+    return value
+
+
+def _error(
+    handler: BaseHTTPRequestHandler,
+    status: int,
+    request_id: str | None = None,
+    code: str = ErrorCode.MALFORMED_REQUEST,
+) -> None:
+    body = ErrorEnvelope(request_id, code).serialize().encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+def _contract_error(handler: BaseHTTPRequestHandler, status: int, error: ContractError) -> None:
+    body = error.to_error_envelope().serialize().encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+class LocalApiServer(ThreadingHTTPServer):
+    allow_reuse_address = True
+    request_queue_size = 16
+
+    def __init__(
+        self, root: Path, port: int = DEFAULT_PORT, authority: CredentialAuthority | None = None
+    ) -> None:
+        self.root, self.authority = root, authority or CredentialAuthority(root)
+        # Ephemeral port zero is test-only; production CLI/configuration still
+        # goes through the bounded valid_port contract.
+        if port != 0:
+            port = valid_port(port)
+        super().__init__((LOOPBACK_ADDRESS, port), LocalApiHandler)
+        self.timeout = REQUEST_TIMEOUT_SECONDS
+
+    def ready(self) -> bool:
+        return readiness(self.root, self.authority)
+
+    def handle_error(self, request: object, client_address: object) -> None:
+        """Avoid socket-level tracebacks and never surface request data."""
+
+        del request, client_address
+
+
+def readiness(root: Path, authority: CredentialAuthority | None = None) -> bool:
+    """Return readiness without creating a second listener."""
+
+    try:
+        connection = open_storage(root)
+        connection.close()
+    except Exception:
+        return False
+    return (authority or CredentialAuthority(root)).ready()
+
+
+class LocalApiHandler(BaseHTTPRequestHandler):
+    server: LocalApiServer
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *_: object) -> None:
+        pass
+
+    def setup(self) -> None:
+        super().setup()
+        self.connection.settimeout(REQUEST_TIMEOUT_SECONDS)
+
+    def _json(self, status: int, payload: dict[str, object]) -> None:
+        body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:
+        if self.path != "/health":
+            _error(self, 404)
+            return
+        ready = self.server.ready()
+        self._json(
+            200 if ready else 503,
+            {"health": "ok" if ready else "not_ready", "healthy": ready, "contract_version": "1.0"},
+        )
+
+    def do_POST(self) -> None:
+        if self.path != "/v1/capabilities":
+            _error(self, 404)
+            return
+        if self.headers.get_content_type() != "application/json":
+            _error(self, 415)
+            return
+        try:
+            size = int(self.headers.get("Content-Length", "-1"))
+        except ValueError:
+            size = -1
+        if not 0 <= size <= MAX_BODY_BYTES:
+            _error(self, 413)
+            return
+        try:
+            envelope = RequestEnvelope.parse(json.loads(self.rfile.read(size)))
+        except ContractError as error:
+            _contract_error(self, 400, error)
+            return
+        except json.JSONDecodeError:
+            _error(self, 400)
+            return
+        if envelope.payload:
+            _error(self, 400, envelope.request_id, ErrorCode.MALFORMED_REQUEST)
+            return
+        if not self.server.ready():
+            _error(self, 503, envelope.request_id, ErrorCode.SERVICE_NOT_READY)
+            return
+        header = self.headers.get("Authorization")
+        if not isinstance(header, str) or not header.startswith("Bearer ") or not header[7:]:
+            _error(self, 401, envelope.request_id, ErrorCode.UNAUTHENTICATED)
+            return
+        scope = self.server.authority.authenticate(header[7:])
+        if scope is None:
+            _error(self, 401, envelope.request_id, ErrorCode.UNAUTHENTICATED)
+            return
+        if not self.server.authority.authorized(scope):
+            _error(self, 403, envelope.request_id, ErrorCode.PROJECT_NOT_AUTHORIZED)
+            return
+        if (
+            scope.consumer_id != envelope.consumer.consumer_id
+            or scope.project_id != envelope.project_id
+        ):
+            _error(self, 403, envelope.request_id, ErrorCode.PROJECT_NOT_AUTHORIZED)
+            return
+        response = ResponseEnvelope(
+            envelope.request_id,
+            {
+                "contract_version": "1.0",
+                "project_id": envelope.project_id,
+                "capabilities": ["contract.foundation"],
+                "read_only": True,
+            },
+        )
+        self._json(200, response.to_dict())
+
+    def do_PUT(self) -> None:
+        _error(self, 405)
+
+    def do_DELETE(self) -> None:
+        _error(self, 405)
+
+    def do_PATCH(self) -> None:
+        _error(self, 405)
+
+    def do_HEAD(self) -> None:
+        _error(self, 405)
+
+    def do_OPTIONS(self) -> None:
+        _error(self, 405)
+
+
+def retirement_status() -> dict[str, object]:
+    """Expose the bounded historical identity classification for tooling."""
+
+    return {
+        "state": "RETIRED",
+        "historical_labels": (HISTORICAL_LEGACY_LABEL, HISTORICAL_NEUTRAL_LABEL),
+        "installable": False,
+        "lifecycle_owned": False,
+        "supported_submission_ingress": False,
+    }

engineering_platform/local_api_keychain.py

@@ -0,0 +1,51 @@
+"""Consumer-side macOS Keychain credential store; never an EP auth authority."""
+
+from __future__ import annotations
+
+import subprocess
+
+SERVICE = "Engineering Platform Local Consumer API"
+
+
+class KeychainError(RuntimeError):
+    """Safe failure category; command diagnostics can contain secret material."""
+
+
+def _account(consumer_id: str, project_id: str) -> str:
+    return f"{consumer_id}:{project_id}"
+
+
+class MacOSKeychainCredentialStore:
+    """Bounded current-user Keychain adapter with no plaintext fallback."""
+
+    def __init__(self, executable: str = "security", service: str = SERVICE) -> None:
+        self.executable, self.service = executable, service
+
+    def _run(self, arguments: list[str], *, input_value: str | None = None) -> subprocess.CompletedProcess[str]:
+        try:
+            return subprocess.run([self.executable, *arguments], input=input_value, text=True, capture_output=True, check=False)
+        except OSError as error:
+            raise KeychainError("macOS Keychain is unavailable.") from error
+
+    def put_credential(self, consumer_id: str, project_id: str, token: str) -> None:
+        result = self._run(["add-generic-password", "-U", "-s", self.service, "-a", _account(consumer_id, project_id), "-w", token])
+        if result.returncode:
+            raise KeychainError("macOS Keychain could not store the credential.")
+
+    def get_credential(self, consumer_id: str, project_id: str) -> str:
+        result = self._run(["find-generic-password", "-w", "-s", self.service, "-a", _account(consumer_id, project_id)])
+        if result.returncode or not result.stdout:
+            raise KeychainError("macOS Keychain credential is missing or unavailable.")
+        return result.stdout.rstrip("\n")
+
+    def delete_credential(self, consumer_id: str, project_id: str) -> None:
+        result = self._run(["delete-generic-password", "-s", self.service, "-a", _account(consumer_id, project_id)])
+        if result.returncode:
+            raise KeychainError("macOS Keychain credential could not be deleted.")
+
+    def credential_present(self, consumer_id: str, project_id: str) -> bool:
+        try:
+            self.get_credential(consumer_id, project_id)
+        except KeychainError:
+            return False
+        return True

engineering_platform/local_repository_binding.py

@@ -0,0 +1,138 @@
+"""Private CENTRAL mappings from logical repositories to local checkout roots.
+
+This is intentionally an operator-only Phase-P bridge.  It does not discover
+checkouts, consult Agent storage, or grant execution authority.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import sqlite3
+
+from .repository_attachment import RepositoryAttachmentError, load_repository_attachment
+
+
+class LocalRepositoryBindingError(ValueError):
+    """A stable, redacted failure for local-binding lifecycle operations."""
+
+
+@dataclass(frozen=True)
+class LocalRepositoryBinding:
+    project_id: str
+    repository_id: str
+    local_root: Path
+    state: str
+    created_at: str
+    updated_at: str
+
+
+def _fail(code: str) -> None:
+    raise LocalRepositoryBindingError(code)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def install_schema(connection: sqlite3.Connection) -> None:
+    connection.execute("""CREATE TABLE IF NOT EXISTS ep_local_repository_bindings (
+        project_id TEXT NOT NULL REFERENCES ep_project_registrations(project_id),
+        repository_id TEXT NOT NULL REFERENCES ep_repository_registrations(repository_id),
+        local_root TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('BOUND','UNBOUND')),
+        created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+        PRIMARY KEY(project_id,repository_id))""")
+    connection.execute("CREATE INDEX IF NOT EXISTS ep_local_repository_bindings_repository_lookup ON ep_local_repository_bindings(repository_id,state)")
+
+
+def _validated_root(local_root: object, *, data_root: Path | None = None) -> Path:
+    if not isinstance(local_root, (str, Path)):
+        _fail("LOCAL_ROOT_INVALID")
+    candidate = Path(local_root).expanduser()
+    if not candidate.is_absolute():
+        _fail("LOCAL_ROOT_NOT_ABSOLUTE")
+    try:
+        root = candidate.resolve(strict=True)
+    except OSError:
+        _fail("LOCAL_ROOT_UNAVAILABLE")
+    if not root.is_dir():
+        _fail("LOCAL_ROOT_NOT_DIRECTORY")
+    # Never allow a filesystem anchor, home directory, CENTRAL data root, or
+    # the installed package/runtime tree to be accidentally treated as a repo.
+    forbidden = {root.anchor, str(Path.home().resolve())}
+    if str(root) in forbidden:
+        _fail("LOCAL_ROOT_UNSAFE")
+    runtime_root = Path(__file__).resolve().parents[1]
+    protected = [runtime_root]
+    if data_root is not None:
+        try:
+            protected.append(data_root.resolve())
+        except OSError:
+            _fail("LOCAL_ROOT_UNAVAILABLE")
+    if any(root == protected_root or root.is_relative_to(protected_root) for protected_root in protected):
+        _fail("LOCAL_ROOT_UNSAFE")
+    return root
+
+
+def _validate_topology(connection: sqlite3.Connection, project_id: str, repository_id: str) -> None:
+    project = connection.execute("SELECT 1 FROM ep_project_registrations WHERE project_id=?", (project_id,)).fetchone()
+    if project is None:
+        _fail("UNKNOWN_PROJECT")
+    repository = connection.execute("SELECT project_id FROM ep_repository_registrations WHERE repository_id=?", (repository_id,)).fetchone()
+    if repository is None:
+        _fail("UNKNOWN_REPOSITORY")
+    if str(repository[0]) != project_id:
+        _fail("PROJECT_REPOSITORY_MISMATCH")
+
+
+def _validate_declaration(root: Path, project_id: str, repository_id: str) -> None:
+    try:
+        declaration = load_repository_attachment(root)
+    except RepositoryAttachmentError:
+        _fail("REPOSITORY_DECLARATION_INVALID")
+    if declaration.project_id != project_id or declaration.repository_id != repository_id:
+        _fail("REPOSITORY_DECLARATION_MISMATCH")
+
+
+def bind_local_repository(
+    connection: sqlite3.Connection, *, project_id: str, repository_id: str,
+    local_root: object, data_root: Path | None = None, rebind: bool = False,
+) -> LocalRepositoryBinding:
+    """Create or deliberately replace the one active path for a repository."""
+    _validate_topology(connection, project_id, repository_id)
+    root = _validated_root(local_root, data_root=data_root)
+    _validate_declaration(root, project_id, repository_id)
+    existing = connection.execute("SELECT local_root,state,created_at FROM ep_local_repository_bindings WHERE project_id=? AND repository_id=?", (project_id, repository_id)).fetchone()
+    if existing is not None and str(existing[0]) != str(root) and not rebind:
+        _fail("LOCAL_BINDING_EXISTS_REBIND_REQUIRED")
+    now = _now()
+    if existing is None:
+        connection.execute("INSERT INTO ep_local_repository_bindings(project_id,repository_id,local_root,state,created_at,updated_at) VALUES(?,?,?,'BOUND',?,?)", (project_id, repository_id, str(root), now, now))
+        created_at = now
+    else:
+        connection.execute("UPDATE ep_local_repository_bindings SET local_root=?,state='BOUND',updated_at=? WHERE project_id=? AND repository_id=?", (str(root), now, project_id, repository_id))
+        created_at = str(existing[2])
+    return LocalRepositoryBinding(project_id, repository_id, root, "BOUND", created_at, now)
+
+
+def resolve_local_repository_binding(connection: sqlite3.Connection, *, project_id: str, repository_id: str, data_root: Path | None = None) -> LocalRepositoryBinding:
+    """Return the current validated root, or fail closed without CWD fallback."""
+    _validate_topology(connection, project_id, repository_id)
+    row = connection.execute("SELECT local_root,state,created_at,updated_at FROM ep_local_repository_bindings WHERE project_id=? AND repository_id=?", (project_id, repository_id)).fetchone()
+    if row is None or str(row[1]) != "BOUND":
+        _fail("LOCAL_BINDING_UNBOUND")
+    root = _validated_root(str(row[0]), data_root=data_root)
+    _validate_declaration(root, project_id, repository_id)
+    return LocalRepositoryBinding(project_id, repository_id, root, "BOUND", str(row[2]), str(row[3]))
+
+
+def unbind_local_repository(connection: sqlite3.Connection, *, project_id: str, repository_id: str) -> None:
+    """Disable the mapping while preserving historical binding evidence."""
+    _validate_topology(connection, project_id, repository_id)
+    now = _now()
+    connection.execute("UPDATE ep_local_repository_bindings SET state='UNBOUND',updated_at=? WHERE project_id=? AND repository_id=?", (now, project_id, repository_id))
+
+
+# Phase-P's exact internal boundary.  The alias keeps call sites free of CLI
+# wording and makes clear that lookup itself supplies no execution eligibility.
+resolve_execution_repository = resolve_local_repository_binding