immich-api 0.2.0__py3-none-any.whl

immich_api/openapi_request.py

@@ -0,0 +1,119 @@
+"""Serialize only parameters and body types declared by an OpenAPI operation."""
+
+import base64
+import json
+from urllib.parse import quote
+
+
+def _value(value):
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, (str, int, float)):
+        return str(value)
+    raise ValueError("Unsupported parameter value")
+
+
+def _path_parameter(path, name, value):
+    rendered = _value(value)
+    if rendered in {".", ".."} or any(c in rendered for c in "/\\%\r\n\x00"):
+        raise ValueError("Unsafe path parameter")
+    return path.replace("{" + name + "}", quote(rendered, safe=""))
+
+
+def _query_parameter(parameter, value):
+    name = parameter["name"]
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        return [(name, _value(value))]
+    rendered = [_value(item) for item in value]
+    if parameter.get("explode", True):
+        return [(name, item) for item in rendered]
+    return [(name, ",".join(rendered))]
+
+
+def _header_parameter(name, value, credential_headers):
+    if name.casefold() in credential_headers:
+        raise ValueError("Authentication headers are controlled by credentials")
+    rendered = _value(value)
+    if any(c in rendered for c in "\r\n\x00"):
+        raise ValueError("Invalid header parameter")
+    return rendered
+
+
+def parameters(operation, arguments, *, credential_headers):
+    path, query, headers = operation["path"], [], {}
+    for parameter in operation["parameters"]:
+        name, location = parameter["name"], parameter["in"]
+        values = arguments.get(location, {})
+        if name not in values:
+            continue
+        value = values[name]
+        if location == "path":
+            path = _path_parameter(path, name, value)
+        elif location == "query":
+            query.extend(_query_parameter(parameter, value))
+        elif location == "header":
+            headers[name] = _header_parameter(name, value, credential_headers)
+    if "{" in path or "}" in path:
+        raise ValueError("Missing path parameter")
+    return path, query, headers
+
+
+def _multipart(body, body_schema, *, definitions, max_bytes):
+    while "$ref" in body_schema:
+        body_schema = definitions[body_schema["$ref"].rsplit("/", 1)[1]]
+    files, data = {}, {}
+    for key, value in body.items():
+        field = body_schema.get("properties", {}).get(key, {})
+        if field.get("contentEncoding") == "base64":
+            decoded = _decode_upload(value, max_bytes)
+            files[key] = ("upload", decoded, "application/octet-stream")
+        else:
+            data[key] = (
+                json.dumps(value, separators=(",", ":"))
+                if isinstance(value, (dict, list))
+                else _value(value)
+            )
+    return _multipart_options(files, data)
+
+
+def _multipart_options(files, data):
+    # HTTPX selects form encoding when files is empty. Optional file fields
+    # must not silently change the operation's declared multipart media type.
+    if files:
+        return {"files": files, "data": data}
+    if data:
+        return {"files": {key: (None, value) for key, value in data.items()}}
+    return {
+        "content": b"--mcp-empty-body--\r\n",
+        "headers": {"Content-Type": "multipart/form-data; boundary=mcp-empty-body"},
+    }
+
+
+def body_options(operation, body, *, definitions, max_bytes):
+    if len(json.dumps(body).encode()) > max_bytes:
+        raise ValueError("Request size limit exceeded")
+    media = operation["content_type"]
+    if media == "application/json":
+        return {"json": body}
+    if media == "application/x-www-form-urlencoded":
+        return {"data": body}
+    if media == "multipart/form-data":
+        return _multipart(
+            body,
+            operation["input"]["properties"]["body"],
+            definitions=definitions,
+            max_bytes=max_bytes,
+        )
+    raise ValueError("Unsupported operation request media type")
+
+
+def _decode_upload(value, max_bytes):
+    try:
+        decoded = base64.b64decode(value, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise ValueError("Invalid base64 upload") from exc
+    if len(decoded) > max_bytes:
+        raise ValueError("Upload size limit exceeded")
+    return decoded

immich_api/openapi_response.py

@@ -0,0 +1,76 @@
+"""Bound response bytes and decode only declared success representations."""
+
+import base64
+import json
+import time
+
+from rfc3986_validator import validate_rfc3986
+
+
+def require_response_status(operation, status):
+    if 200 <= status < 300 or str(status) in operation.get("redirect_responses", {}):
+        return
+    raise RuntimeError(f"Provider returned HTTP {status}; no automatic retry")
+
+
+def _redirect_data(response):
+    values = response.headers.get_list("location")
+    if len(values) != 1:
+        raise ValueError("Redirect requires exactly one Location header")
+    location = values[0]
+    if not location.isprintable() or not validate_rfc3986(location, rule="URI"):
+        raise ValueError(
+            "Redirect Location must be an absolute URI without unsafe characters"
+        )
+    return "", {"location": location}
+
+
+def read_body(response, max_bytes, *, deadline):
+    body = bytearray()
+    for chunk in response.iter_bytes():
+        if time.monotonic() > deadline or len(body) + len(chunk) > max_bytes:
+            raise RuntimeError("Provider response limit exceeded")
+        body.extend(chunk)
+    return body
+
+
+def _decode_json(body):
+    try:
+        return json.loads(body)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ValueError("Provider response is not JSON") from exc
+
+
+def _decode_text(body, encoding):
+    try:
+        return body.decode(encoding or "utf-8")
+    except (UnicodeDecodeError, LookupError) as exc:
+        raise ValueError("Provider text response cannot be decoded") from exc
+
+
+def decode_body(operation, response, body):
+    status = str(response.status_code)
+    if status in operation.get("redirect_responses", {}):
+        return _redirect_data(response)
+    return _declared_body(operation, response, body)
+
+
+def _declared_body(operation, response, body):
+    status = str(response.status_code)
+    expected = operation["responses"].get(status)
+    if expected is None:
+        raise ValueError("Undeclared provider success status")
+    if not expected:
+        if body:
+            raise ValueError("Unexpected provider response body")
+        return "", None
+    content_type = response.headers.get("content-type", "").split(";", 1)[0].strip()
+    if content_type not in expected:
+        raise ValueError("Undeclared provider response media type")
+    mode = operation["response_modes"][status][content_type]
+    decoders = {
+        "json": lambda: _decode_json(body),
+        "text": lambda: _decode_text(body, response.charset_encoding),
+    }
+    data = decoders.get(mode, lambda: base64.b64encode(body).decode())()
+    return content_type, data

immich_api/openapi_runtime.py

@@ -0,0 +1,203 @@
+"""Generated operation-bound vendor client and SDK MCP tool registration."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import regex
+from agent_connector_sdk.config import setting
+from agent_connector_sdk.http.client import create_http_client
+from agent_connector_sdk.http.options import HttpClientOptions
+from agent_connector_sdk.http.retry import RetryPolicy
+from agent_connector_sdk.mcp.concurrency import run_blocking
+from fastmcp.tools import Tool, ToolResult
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import ValidationError
+from jsonschema.validators import extend
+from mcp.types import InputRequiredResult, ToolAnnotations
+from pydantic import Field
+
+from .openapi_auth_scheme import credential_headers
+from .openapi_execution import confirm_write, require_origin
+from .openapi_request import body_options, parameters
+from .openapi_response import decode_body, read_body, require_response_status
+from .parity.openapi_discovery import configure_discovery
+
+CONTRACT = json.loads(Path(__file__).with_name("openapi_contract.json").read_text())
+MAX_BYTES = 16 * 1024 * 1024
+
+
+def _pattern(*arguments):
+    """Adapt the four-argument jsonschema keyword callback."""
+    _validator, pattern, instance, _schema = arguments
+    if (
+        isinstance(instance, str)
+        and regex.search(pattern, instance, timeout=0.1) is None
+    ):
+        yield ValidationError("String does not satisfy its pattern")
+
+
+def _format(*arguments):
+    """Require actual format assertions; retain OpenAPI representation annotations."""
+    validator, name, _instance, _schema = arguments
+    if name in {"int32", "int64", "float", "double", "binary", "byte", "password"}:
+        return
+    checker = validator.format_checker
+    if checker is None or name not in checker.checkers:
+        raise RuntimeError(f"Required OpenAPI format checker is unavailable: {name}")
+    yield from Draft202012Validator.VALIDATORS["format"](*arguments)
+
+
+SchemaValidator = extend(Draft202012Validator, {"pattern": _pattern, "format": _format})
+
+
+def validate(value, definition):
+    """Validate without disclosing caller input or provider response values."""
+    validator = SchemaValidator(definition, format_checker=FormatChecker())
+    if next(validator.iter_errors(value), None) is not None:
+        raise ValueError("Value does not satisfy the declared OpenAPI schema")
+
+
+class OpenApiClient:
+    """Dispatch only catalogued actions; perform each HTTP request exactly once."""
+
+    def __init__(
+        self,
+        base_url,
+        auth,
+        tls_profile=None,
+        *,
+        credential_scheme=None,
+        write_mode="read-only",
+        allow_plaintext=False,
+        transport=None,
+    ):
+        if write_mode not in {"read-only", "read-write"}:
+            raise ValueError("Unsupported OpenAPI write mode")
+        require_origin(
+            base_url,
+            credential_scheme=credential_scheme,
+            allow_plaintext=allow_plaintext,
+        )
+        self.session = create_http_client(
+            HttpClientOptions(
+                base_url=base_url,
+                auth=auth,
+                tls=tls_profile,
+                retry=RetryPolicy(max_attempts=1),
+                allow_plaintext=allow_plaintext,
+                timeout=30.0,
+            ),
+            transport=transport,
+        )
+        self.credential_scheme = credential_scheme
+        self.allow_writes = write_mode == "read-write"
+
+    def close(self):
+        self.session.close()
+
+    def execute(self, domain: str, arguments: dict[str, Any]):
+        if domain not in CONTRACT["domains"]:
+            raise ValueError("Unknown domain")
+        validate(arguments, CONTRACT["schemas"][domain][0])
+        operation = CONTRACT["operations"][arguments["action"]]
+        if operation["domain"] != domain:
+            raise ValueError("Action is outside this domain")
+        if not operation["read_only"] and not self.allow_writes:
+            raise PermissionError("Writes require explicit operator enablement")
+        self._require_credentials(operation["security"])
+        path, query, headers = parameters(
+            operation,
+            arguments,
+            credential_headers=credential_headers(CONTRACT["security_schemes"]),
+        )
+        target = self.session.base_url.join(path)
+        origin = self.session.base_url
+        if (target.scheme, target.host, target.port) != (
+            origin.scheme,
+            origin.host,
+            origin.port,
+        ):
+            raise ValueError(
+                "Operation must stay within the configured provider origin"
+            )
+        options = {"params": query, "headers": headers, "follow_redirects": False}
+        if "body" in arguments:
+            body = body_options(
+                operation,
+                arguments["body"],
+                definitions=CONTRACT["definitions"],
+                max_bytes=MAX_BYTES,
+            )
+            options["headers"].update(body.pop("headers", {}))
+            options.update(body)
+        return self._send(operation, path, options)
+
+    def _require_credentials(self, requirements):
+        if requirements and not any(
+            not choice or set(choice) == {self.credential_scheme}
+            for choice in requirements
+        ):
+            raise PermissionError("Action requires a supported credential reference")
+
+    def _send(self, operation, path, options):
+        deadline = time.monotonic() + 60
+        with self.session.stream(operation["method"], path, **options) as response:
+            require_response_status(operation, response.status_code)
+            body = read_body(response, MAX_BYTES, deadline=deadline)
+            content_type, data = decode_body(operation, response, body)
+            result = {
+                "action": operation["action"],
+                "status": response.status_code,
+                "content_type": content_type,
+                "data": data,
+            }
+            validate(result, CONTRACT["schemas"][operation["domain"]][1])
+            return result
+
+
+class OpenApiTool(Tool):
+    """One domain, discriminated action inputs, and declared response variants."""
+
+    domain: str = Field(exclude=True)
+    client_factory: Any = Field(exclude=True)
+
+    async def run(self, arguments):
+        validate(arguments, self.parameters)
+        operation = CONTRACT["operations"][arguments["action"]]
+        client = self.client_factory()
+        confirmation = await confirm_write(operation, arguments, client)
+        if isinstance(confirmation, InputRequiredResult):
+            return confirmation
+        result = await run_blocking(client.execute, self.domain, arguments)
+        return ToolResult(structured_content=result)
+
+
+def register_domain(mcp, domain, client_factory):
+    configure_discovery(mcp, setting("IMMICH_API_MCP_CLIENT_BUDGET"))
+    operations = [
+        CONTRACT["operations"][action] for action in CONTRACT["domains"][domain]
+    ]
+    read_only = all(operation["read_only"] for operation in operations)
+    inputs, outputs = CONTRACT["schemas"][domain]
+    mcp.add_tool(
+        OpenApiTool(
+            name=f"{domain}_operations",
+            domain=domain,
+            client_factory=client_factory,
+            description="Bound OpenAPI operations: "
+            + ", ".join(CONTRACT["domains"][domain]),
+            parameters=inputs,
+            output_schema=outputs,
+            tags={domain},
+            annotations=ToolAnnotations(
+                readOnlyHint=read_only,
+                destructiveHint=not read_only,
+                idempotentHint=False,
+                openWorldHint=True,
+            ),
+        )
+    )

immich_api/parity/__init__.py

@@ -0,0 +1,17 @@
+"""Self-contained generated API/MCP parity checks; no sibling builder required."""
+
+from .openapi_parity import (
+    operation_inventory,
+    require_complete_coverage,
+    verify_contract,
+    verify_mcp,
+)
+from .openapi_transport_parity import verify_transport
+
+__all__ = [
+    "operation_inventory",
+    "require_complete_coverage",
+    "verify_contract",
+    "verify_mcp",
+    "verify_transport",
+]

immich_api/parity/check_openapi_parity.py

@@ -0,0 +1,173 @@
+"""Verify a pinned source, generated inventory and API/native MCP contract parity.
+
+This invokes native listing and schema search only. It does not prove transport execution or call a
+provider; exhaustive mocked dispatch and live endpoint checks are separate.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import importlib
+import json
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+
+if __package__:
+    from .openapi_discovery import inspect_discovery
+    from .openapi_parity import (
+        require_declared_authorization,
+        verify_contract,
+        verify_mcp,
+    )
+    from .openapi_schema_budget import client_budget as validate_budget
+else:
+    from openapi_discovery import inspect_discovery
+    from openapi_parity import (
+        require_declared_authorization,
+        verify_contract,
+        verify_mcp,
+    )
+    from openapi_schema_budget import client_budget as validate_budget
+
+
+def package_modules(package_name):
+    return [
+        name
+        for name in sys.modules
+        if name == package_name or name.startswith(package_name + ".")
+    ]
+
+
+@contextmanager
+def project_imports(package):
+    """Check the requested tree even when another package has the same name."""
+    previous = {name: sys.modules[name] for name in package_modules(package.name)}
+    search_path = list(sys.path)
+    for name in previous:
+        del sys.modules[name]
+    sys.path.insert(0, str(package.parent))
+    try:
+        yield
+    finally:
+        for name in package_modules(package.name):
+            del sys.modules[name]
+        sys.modules.update(previous)
+        sys.path[:] = search_path
+
+
+async def native_tools(package, contract, budget=None, *, ready=False):
+    try:
+        from fastmcp import Client
+    except ImportError as exc:
+        raise RuntimeError(
+            "Native parity requires the connector's existing environment"
+        ) from exc
+    with project_imports(package):
+        server = importlib.import_module(f"{package.name}.mcp_server")
+        instance = server.build_server(command_args=["--transport", "stdio"])
+        if ready and getattr(
+            instance, "_openapi_schema_budget", None
+        ) != validate_budget(budget):
+            raise ValueError(
+                "Ready requires the matching client budget to be active in the normal runtime configuration"
+            )
+        if budget is not None:
+            return await inspect_discovery(
+                instance, [f"{name}_operations" for name in contract["domains"]], budget
+            )
+        async with Client(instance) as client:
+            return await asyncio.wait_for(client.list_tools(), timeout=45), None
+
+
+def check(
+    spec,
+    package,
+    *,
+    native=False,
+    mode="ready",
+    client_budget=None,
+    overlay_path=None,
+    expected_overlay_sha256=None,
+    evidence_root=None,
+):
+    if mode not in ("ready", "inspect"):
+        raise ValueError("Unknown readiness mode")
+    ready = mode == "ready"
+    source = spec.read_bytes()
+    contract = json.loads((package / "openapi_contract.json").read_text())
+    inventory = verify_contract(
+        json.loads(source),
+        contract,
+        hashlib.sha256(source).hexdigest(),
+        source_bytes=source,
+        overlay_bytes=overlay_path.read_bytes() if overlay_path else None,
+        expected_overlay_sha256=expected_overlay_sha256,
+        evidence_root=evidence_root,
+    )
+    saved = json.loads((package / "openapi_inventory.json").read_text())
+    if saved != inventory:
+        raise ValueError("Stale or incomplete operation inventory")
+    if ready:
+        require_declared_authorization(inventory)
+        if not native or client_budget is None:
+            raise ValueError(
+                "Ready requires native validation and an explicit named client budget"
+            )
+    result = {
+        "source_sha256": inventory["source_sha256"],
+        "path_count": inventory["path_count"],
+        "api_contract_operations": inventory["operation_count"],
+        "mocked_transport_verified": False,
+        "live_endpoint_verified": False,
+        "ready": False,
+        "readiness_scope": "Source, authorization evidence and budgeted native schemas; excludes transport/live acceptance",
+    }
+    if native:
+        tools, disclosure = asyncio.run(
+            native_tools(package, contract, client_budget, ready=ready)
+        )
+        result["native_mcp"] = verify_mcp(contract, tools)
+        result["disclosure"] = disclosure
+        result["ready"] = ready
+    else:
+        result["native_mcp"] = "not checked"
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("spec", type=Path)
+    parser.add_argument("package", type=Path)
+    parser.add_argument("--native", action="store_true")
+    parser.add_argument(
+        "--inspect", action="store_true", help="Inspect without claiming readiness"
+    )
+    parser.add_argument("--client-budget", type=Path)
+    parser.add_argument("--provider-overlay", type=Path)
+    parser.add_argument("--expected-overlay-sha256")
+    parser.add_argument("--evidence-root", type=Path)
+    args = parser.parse_args()
+    print(
+        json.dumps(
+            check(
+                args.spec.resolve(),
+                args.package.resolve(),
+                native=args.native,
+                mode="inspect" if args.inspect else "ready",
+                client_budget=args.client_budget,
+                overlay_path=args.provider_overlay,
+                expected_overlay_sha256=args.expected_overlay_sha256,
+                evidence_root=args.evidence_root,
+            ),
+            indent=2,
+            sort_keys=True,
+        ),
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()

immich_api/parity/openapi_discovery.py

@@ -0,0 +1,95 @@
+"""Budgeted disclosure using FastMCP's existing search transform and call path."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+
+if __package__:
+    from .openapi_schema_budget import client_budget, require_schema_budget, wire_tool
+else:
+    from openapi_schema_budget import client_budget, require_schema_budget, wire_tool
+
+
+def enforce_disclosure(tools, budget, *, kind="listing"):
+    """Keep a budget failure explicit on the native JSON-RPC error path."""
+    from mcp.shared.exceptions import MCPError
+    from mcp.types import INTERNAL_ERROR
+
+    try:
+        return require_schema_budget(tools, budget, kind=kind)
+    except ValueError as exc:
+        raise MCPError(INTERNAL_ERROR, str(exc)) from exc
+
+
+def configure_discovery(server, budget=None):
+    """Retain all tools and policies; bound listing and exact search responses."""
+    if budget is None:
+        return
+    budget = client_budget(budget)
+    previous = getattr(server, "_openapi_schema_budget", None)
+    if previous is not None:
+        if previous != budget:
+            raise ValueError("Cannot replace a server's configured client budget")
+        return
+    from fastmcp.server.transforms import Transform
+    from fastmcp.server.transforms.search import RegexSearchTransform
+
+    def serialize(tools):
+        values = [wire_tool(tool) for tool in tools]
+        enforce_disclosure(values, budget, kind="search_result")
+        return values
+
+    class Search(RegexSearchTransform):
+        async def transform_tools(self, tools):
+            result = await super().transform_tools(tools)
+            enforce_disclosure(result, budget)
+            return result
+
+    class Eager(Transform):
+        async def list_tools(self, tools):
+            enforce_disclosure(tools, budget)
+            return tools
+
+    transform = (
+        Search(max_results=1, search_result_serializer=serialize)
+        if budget["discovery"] == "regex-search"
+        else Eager()
+    )
+    server.add_transform(transform)
+    server._openapi_schema_budget = budget
+
+
+async def inspect_discovery(server, names, budget):
+    """Use native listing/search to measure and retrieve every expected schema."""
+    from fastmcp import Client
+
+    budget = client_budget(budget)
+    configure_discovery(server, budget)
+    async with Client(server) as client:
+        listed = await asyncio.wait_for(client.list_tools(), timeout=45)
+        receipt = {"initial": require_schema_budget(listed, budget), "retrievals": {}}
+        if budget["discovery"] == "eager":
+            return listed, receipt
+        tools = []
+        for name in sorted(names):
+            result = await asyncio.wait_for(
+                client.call_tool(
+                    "search_tools", {"pattern": "^" + re.escape(name) + r"(?:\s|$)"}
+                ),
+                timeout=15,
+            )
+            rows = result.data
+            if isinstance(rows, dict):
+                rows = rows.get("result")
+            if (
+                not isinstance(rows, list)
+                or len(rows) != 1
+                or rows[0].get("name") != name
+            ):
+                raise ValueError(f"Exact schema retrieval failed: {name}")
+            receipt["retrievals"][name] = require_schema_budget(
+                rows, budget, kind="search_result"
+            )
+            tools.extend(rows)
+        return tools, receipt