immich-api 0.2.0__py3-none-any.whl

immich_api/parity/openapi_parity.py

@@ -0,0 +1,239 @@
+"""Complete source inventories and API/MCP contract parity, without provider calls."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+
+if __package__:
+    from .openapi_provider_overlay import apply_provider_overlay
+    from .openapi_schema import compile_contract, domain_schemas
+    from .openapi_security import validate_requirements, validate_security
+    from .openapi_source_parity import source_route, verify_source_routes
+else:
+    from openapi_provider_overlay import apply_provider_overlay
+    from openapi_schema import compile_contract, domain_schemas
+    from openapi_security import validate_requirements, validate_security
+    from openapi_source_parity import source_route, verify_source_routes
+
+HTTP_METHODS = frozenset(
+    {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+)
+
+
+def digest(value):
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def _operation_entry(document, path, *, method, operation):
+    return {
+        **source_route(document, path, operation),
+        "method": method.upper(),
+        "source_path": path,
+        "security": operation.get("security", document.get("security", [])),
+        "security_declaration": (
+            "operation"
+            if "security" in operation
+            else "root"
+            if "security" in document
+            else "unknown"
+        ),
+        "extensions": {
+            key: value for key, value in operation.items() if key.startswith("x-")
+        },
+        "deprecated": operation.get("deprecated", False),
+        "tags": operation.get("tags", []),
+        "operation_sha256": digest(operation),
+    }
+
+
+def operation_inventory(document, source_sha256):
+    """Enumerate the entire pinned source, independently of compiler filtering."""
+    document = copy.deepcopy(document)
+    schemes = validate_security(document)
+    operations = {}
+    for path, item in sorted(document["paths"].items()):
+        for method, operation in sorted(item.items()):
+            if method not in HTTP_METHODS:
+                continue
+            action = operation["operationId"]
+            if action in operations:
+                raise ValueError(f"Duplicate source operation: {action}")
+            operations[action] = _operation_entry(
+                document, path, method=method, operation=operation
+            )
+            operations[action]["path_parameters_sha256"] = digest(
+                item.get("parameters", [])
+            )
+    if not operations:
+        raise ValueError("Source declares no HTTP operations")
+    return {
+        "version": 1,
+        "source_sha256": source_sha256,
+        "source_info": document.get("info", {}),
+        "openapi_version": document["openapi"],
+        "security_schemes": schemes,
+        "path_count": len(document["paths"]),
+        "operation_count": len(operations),
+        "operations": dict(sorted(operations.items())),
+        "scope": "All operations in this pinned OpenAPI source; upstream suite completeness requires separate evidence.",
+        "live_verified": False,
+    }
+
+
+def require_declared_authorization(inventory):
+    """Schema omission is not proof that an operation is public."""
+    for operation in inventory["operations"].values():
+        validate_requirements(
+            operation["security"],
+            inventory["security_schemes"],
+            openapi_version=inventory["openapi_version"],
+        )
+    classified = {
+        item["operation_id"]
+        for item in inventory.get("provider_overlay", {}).get(
+            "authorization_classifications", []
+        )
+    }
+    unknown = [
+        action
+        for action, operation in inventory["operations"].items()
+        if operation["security_declaration"] == "unknown" and action not in classified
+    ]
+    if unknown:
+        raise ValueError(
+            f"Authorization classification requires reviewed provider evidence: {unknown}"
+        )
+
+
+def require_complete_coverage(contract, api_actions, mcp_actions):
+    """Call with successful probe IDs, not discovery IDs, for transport coverage."""
+    expected = set(contract["operations"])
+    for label, actions in (("API", list(api_actions)), ("MCP", list(mcp_actions))):
+        if len(actions) != len(set(actions)):
+            raise ValueError(f"Duplicate {label} coverage IDs")
+        missing, extra = (
+            sorted(expected - set(actions)),
+            sorted(set(actions) - expected),
+        )
+        if missing or extra:
+            raise ValueError(
+                f"Incomplete {label} coverage: missing={missing}, extra={extra}"
+            )
+    return {"api_operations": len(expected), "mcp_operations": len(expected)}
+
+
+def source_context(
+    document,
+    source_sha256,
+    *,
+    source_bytes=None,
+    overlay_bytes=None,
+    expected_overlay_sha256=None,
+    evidence_root=None,
+):
+    inventory = operation_inventory(document, source_sha256)
+    if overlay_bytes is None:
+        if expected_overlay_sha256 is not None or evidence_root is not None:
+            raise ValueError("Provider evidence options require an exact overlay")
+        return document, inventory
+    if (
+        not isinstance(source_bytes, bytes)
+        or hashlib.sha256(source_bytes).hexdigest() != source_sha256
+        or json.loads(source_bytes) != document
+    ):
+        raise ValueError("Provider correction requires the exact raw source bytes")
+    effective, receipt = apply_provider_overlay(
+        source_bytes,
+        overlay_bytes,
+        expected_overlay_sha256=expected_overlay_sha256,
+        evidence_root=evidence_root,
+    )
+    inventory["provider_overlay"] = receipt
+    return effective, inventory
+
+
+def verify_contract(document, contract, source_sha256, **provider_options):
+    """Reject source omissions and exact method, route, parameter or schema drift."""
+    effective, inventory = source_context(document, source_sha256, **provider_options)
+    # A compiler must not be able to mutate the independent source inventory.
+    expected = compile_contract(
+        copy.deepcopy(effective),
+        response_corrections=inventory.get("provider_overlay", {}).get(
+            "response_corrections", []
+        ),
+    )
+    if set(inventory["operations"]) != set(expected["operations"]):
+        raise ValueError("Compiler omitted or invented source operations")
+    expected["source_sha256"] = source_sha256
+    if "provider_overlay" in inventory:
+        expected["provider_overlay"] = inventory["provider_overlay"]
+    verify_source_routes(inventory, expected)
+    verify_source_routes(inventory, contract)
+    expected["schemas"] = {
+        domain: domain_schemas(expected, domain) for domain in expected["domains"]
+    }
+    # JSON round-trip accounts only for tuples in the compiler's return value.
+    if contract != json.loads(json.dumps(expected)):
+        raise ValueError("API contract differs from complete source compilation")
+    mapped = [action for actions in contract["domains"].values() for action in actions]
+    require_complete_coverage(contract, mapped, mapped)
+    for domain, actions in contract["domains"].items():
+        if any(
+            contract["operations"][action]["domain"] != domain for action in actions
+        ):
+            raise ValueError("Operation is unreachable through its declared domain")
+    return inventory
+
+
+def verify_mcp(contract, tools):
+    """Compare actual native tools/list results, including every action branch."""
+    try:
+        from agent_connector_sdk.manifest.tool_schema import read_field
+    except ImportError as exc:
+        raise RuntimeError("MCP parity requires the reviewed SDK environment") from exc
+    names = [read_field(tool, "name") for tool in tools]
+    if len(names) != len(set(names)):
+        raise ValueError("Duplicate MCP tool names")
+    by_name = dict(zip(names, tools, strict=True))
+    covered = []
+    for domain, actions in contract["domains"].items():
+        name = f"{domain}_operations"
+        if name not in by_name:
+            raise ValueError(f"Unreachable MCP domain: {domain}")
+        _verify_tool_schema(by_name[name], contract["schemas"][domain], name)
+        covered.extend(actions)
+    require_complete_coverage(contract, contract["operations"], covered)
+    return {"domains": len(contract["domains"]), "exposed_operations": len(covered)}
+
+
+def _verify_tool_schema(tool, schemas, name):
+    from agent_connector_sdk.manifest.tool_schema import (
+        canonical_input_schema,
+        canonical_output_schema,
+    )
+    from fastmcp.utilities.json_schema import dereference_refs
+    from jsonschema import Draft202012Validator
+    from jsonschema.exceptions import SchemaError
+
+    inputs, outputs = schemas
+    expected = {"inputSchema": inputs, "outputSchema": outputs}
+    # Use FastMCP's actual bounded serve-time transformation. It preserves
+    # reference siblings and retains references for recursive/large graphs.
+    expanded = {
+        "inputSchema": dereference_refs(inputs),
+        "outputSchema": dereference_refs(outputs),
+    }
+    for canonical in (canonical_input_schema, canonical_output_schema):
+        actual = canonical(tool)
+        try:
+            Draft202012Validator.check_schema(actual)
+        except SchemaError as exc:
+            raise ValueError(
+                f"Native MCP schema is unsupported by client validation: {name}"
+            ) from exc
+        if actual != canonical(expected) and actual != canonical(expanded):
+            raise ValueError(f"MCP schema differs from API contract: {name}")

immich_api/parity/openapi_provider_evidence.py

@@ -0,0 +1,143 @@
+"""Verify local provider evidence without following paths outside its capture root."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from contextlib import ExitStack
+from pathlib import Path
+
+_EVIDENCE = {"path": str, "sha256": str}
+_EVIDENCE_OPTIONAL = {"git_blob": str, "source_commit": str}
+_MAX_EVIDENCE_BYTES = 16 * 1024 * 1024
+
+
+def _pairs(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("Duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _hash(value):
+    data = (
+        value
+        if isinstance(value, bytes)
+        else json.dumps(
+            value,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=True,
+            allow_nan=False,
+        ).encode()
+    )
+    return hashlib.sha256(data).hexdigest()
+
+
+def _fields(value, required, optional=None):
+    rules = required | (optional or {})
+    if (
+        not isinstance(value, dict)
+        or not required.keys() <= value.keys()
+        or value.keys() - rules.keys()
+    ):
+        raise ValueError("Unsupported or missing overlay fields")
+    for name, item in value.items():
+        if type(item) is not rules[name] or (
+            isinstance(item, str) and not item.strip()
+        ):
+            raise ValueError("Invalid overlay field type or empty string")
+
+
+def _read_file(root, relative):
+    try:
+        return _safe_read(root, relative)
+    except OSError as exc:
+        raise ValueError("Evidence file is missing, unsafe, or unreadable") from exc
+
+
+def _safe_read(root, relative):
+    if os.name != "posix":
+        raise ValueError(
+            "Secure evidence verification requires POSIX descriptor operations"
+        )
+    parts = relative.split("/")
+    if "\\" in relative or any(part in {"", ".", ".."} for part in parts):
+        raise ValueError("Evidence path must be a contained relative path")
+    parts = [*Path(root).absolute().parts[1:], *parts]
+    with ExitStack() as stack:
+        directory = os.open("/", os.O_RDONLY | os.O_DIRECTORY)
+        stack.callback(os.close, directory)
+        for part in parts[:-1]:
+            directory = os.open(
+                part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=directory
+            )
+            stack.callback(os.close, directory)
+        fd = os.open(
+            parts[-1], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory
+        )
+        stream = stack.enter_context(os.fdopen(fd, "rb"))
+        if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+            raise ValueError("Evidence must be a regular non-symlink file")
+        data = stream.read(_MAX_EVIDENCE_BYTES + 1)
+    if data[_MAX_EVIDENCE_BYTES:]:
+        raise ValueError("Evidence file exceeds the size limit")
+    return data
+
+
+def _evidence(records, root):
+    verified = {}
+    for record in records:
+        _fields(record, _EVIDENCE, _EVIDENCE_OPTIONAL)
+        path = record["path"]
+        if path in verified:
+            raise ValueError("Duplicate evidence path")
+        data = _read_file(root, path)
+        if _hash(data) != record["sha256"]:
+            raise ValueError("Evidence SHA256 mismatch")
+        if "source_commit" in record and not re.fullmatch(
+            r"[0-9a-f]{40}(?:[0-9a-f]{24})?", record["source_commit"]
+        ):
+            raise ValueError("Evidence source commit must be an immutable Git ID")
+        blob = b"blob " + str(len(data)).encode() + b"\0" + data
+        blobs = {hashlib.sha1(blob, usedforsecurity=False).hexdigest(), _hash(blob)}
+        if "git_blob" in record and record["git_blob"] not in blobs:
+            raise ValueError("Evidence Git blob mismatch")
+        verified[path] = (record, len(data.splitlines()), blobs)
+    return verified
+
+
+def _reference(reference, evidence):
+    _fields(
+        reference,
+        _EVIDENCE,
+        _EVIDENCE_OPTIONAL | {"line_start": int, "line_end": int, "url": str},
+    )
+    record, lines, blobs = evidence.get(reference["path"], ({}, 0, set()))
+    if reference["sha256"] != record.get("sha256"):
+        raise ValueError("Missing or stale authorization evidence")
+    if ("git_blob" in reference and reference["git_blob"] not in blobs) or (
+        "source_commit" in reference
+        and reference["source_commit"] != record.get("source_commit")
+    ):
+        raise ValueError("Authorization evidence Git identity mismatch")
+    start, end = reference.get("line_start", 1), reference.get("line_end", lines)
+    if not 1 <= start <= end <= lines:
+        raise ValueError("Authorization evidence line range is invalid")
+    return _hash(reference)
+
+
+def _references(references, evidence):
+    if not references:
+        raise ValueError("Authorization classification requires provider evidence")
+    seen = set()
+    for reference in references:
+        digest = _reference(reference, evidence)
+        if digest in seen:
+            raise ValueError("Duplicate authorization evidence")
+        seen.add(digest)

immich_api/parity/openapi_provider_overlay.py

@@ -0,0 +1,239 @@
+"""Apply reviewed additive schema corrections; retain auth evidence as a sidecar.
+
+Version 1 supports named component object schemas and explicit public decorators.
+Version 2 additionally permits a reviewed GET empty-200 to header-data 307 correction.
+It cannot repair routes, remove constraints, create credentials, or grant readiness.
+Component/operation hashes use compact sorted JSON; the effective document uses
+sorted, indented UTF-8 JSON with a final newline. Both use ensure_ascii=True.
+Evidence verification requires POSIX descriptor operations and fails closed elsewhere.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+
+if __package__:
+    from .openapi_provider_evidence import (
+        _evidence,
+        _fields,
+        _hash,
+        _pairs,
+        _references,
+    )
+    from .openapi_provider_responses import apply_response_corrections
+    from .openapi_security import validate_security
+else:
+    from openapi_provider_evidence import _evidence, _fields, _hash, _pairs, _references
+    from openapi_provider_responses import apply_response_corrections
+    from openapi_security import validate_security
+
+_METHODS = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+_BINDING = dict.fromkeys(
+    ("operation_id", "method", "path", "source_operation_sha256"), str
+)
+_CORRECTION = dict.fromkeys(
+    (
+        "op",
+        "schema_pointer",
+        "property",
+        "before_sha256",
+        "after_sha256",
+        "source_commit",
+        "source_file",
+        "source_file_sha256",
+    ),
+    str,
+)
+
+
+def _target(document, correction):
+    _fields(correction, _CORRECTION)
+    pointer = correction["schema_pointer"]
+    if correction["op"] != "require-property" or not re.fullmatch(
+        r"/components/schemas/(?:[^~/]|~[01])+", pointer
+    ):
+        raise ValueError(
+            "Only named component require-property corrections are supported"
+        )
+    name = pointer.removeprefix("/components/schemas/")
+    name = name.replace("~1", "/").replace("~0", "~")
+    schemas = document.get("components", {}).get("schemas", {})
+    if not isinstance(schemas, dict):
+        raise ValueError("Schema components must be an object")
+    target = schemas.get(name)
+    if (
+        not isinstance(target, dict)
+        or target.get("type", "object") != "object"
+        or "$ref" in target
+        or not isinstance(target.get("properties"), dict)
+    ):
+        raise ValueError("Correction must target an existing object schema")
+    return target
+
+
+def _require_property(document, correction, evidence):
+    target = _target(document, correction)
+    prop, required = correction["property"], target.get("required", [])
+    if not isinstance(required, list) or any(
+        not isinstance(item, str) for item in required
+    ):
+        raise ValueError("Malformed source required array")
+    if (
+        prop not in target["properties"]
+        or prop in required
+        or len(required) != len(set(required))
+    ):
+        raise ValueError(
+            "Correction must add one existing, previously optional property"
+        )
+    record = evidence.get(correction["source_file"], ({},))[0]
+    if (record.get("sha256"), record.get("source_commit")) != (
+        correction["source_file_sha256"],
+        correction["source_commit"],
+    ):
+        raise ValueError("Correction is not bound to verified provider evidence")
+    if _hash(target) != correction["before_sha256"]:
+        raise ValueError("Stale correction schema hash")
+    target["required"] = [*required, prop]
+    if _hash(target) != correction["after_sha256"]:
+        raise ValueError("Correction after schema hash mismatch")
+
+
+def _operations(document):
+    result = {}
+    for path, item in document.get("paths", {}).items():
+        if "$ref" in item:
+            raise ValueError("Path references require an explicit adapter")
+        for method, operation in item.items():
+            if method not in _METHODS:
+                continue
+            action = operation.get("operationId")
+            if not isinstance(action, str) or not action or action in result:
+                raise ValueError("Missing or duplicate source operation ID")
+            result[action] = {
+                "operation_id": action,
+                "method": method.upper(),
+                "path": path,
+                "source_operation_sha256": _hash(operation),
+                "unknown": "security" not in operation and "security" not in document,
+            }
+    return result
+
+
+def _classification(entry, operations, evidence):
+    _fields(
+        entry,
+        _BINDING
+        | {
+            "reviewed_guard_classification": str,
+            "precondition_category": str,
+            "preconditions": str,
+            "source_evidence": list,
+        },
+    )
+    source = operations.get(entry["operation_id"], {})
+    if not source.get("unknown") or any(entry[key] != source[key] for key in _BINDING):
+        raise ValueError(
+            "Authorization classification has a stale, extra, or already declared operation"
+        )
+    if entry[
+        "reviewed_guard_classification"
+    ] != "explicit-public-decorator" or not re.fullmatch(
+        r"[a-z][a-z0-9-]{0,63}", entry["precondition_category"]
+    ):
+        raise ValueError(
+            "Unsupported authorization classification or precondition category"
+        )
+    _references(entry["source_evidence"], evidence)
+
+
+def _apply(document, overlay, evidence):
+    operations, corrections, classified = _operations(document), set(), set()
+    for correction in overlay["corrections"]:
+        _fields(correction, _CORRECTION)
+        key = (correction["schema_pointer"], correction["property"])
+        if key in corrections:
+            raise ValueError("Duplicate schema correction")
+        _require_property(document, correction, evidence)
+        corrections.add(key)
+    for entry in overlay["authorization_classifications"]:
+        _classification(entry, operations, evidence)
+        action = entry["operation_id"]
+        if action in classified:
+            raise ValueError("Duplicate authorization classification")
+        classified.add(action)
+    apply_response_corrections(
+        document,
+        overlay.get("response_corrections", []),
+        operations=operations,
+        evidence=evidence,
+    )
+    return sorted(
+        action
+        for action, operation in operations.items()
+        if operation["unknown"] and action not in classified
+    )
+
+
+def _overlay_fields(overlay):
+    version = overlay.get("version") if isinstance(overlay, dict) else None
+    response_fields = {"response_corrections": list} if version == 2 else {}
+    _fields(
+        overlay,
+        {
+            "version": int,
+            "raw_source_sha256": str,
+            "effective_source_sha256": str,
+            "evidence_files": list,
+            "corrections": list,
+            "authorization_classifications": list,
+        }
+        | response_fields,
+    )
+    return overlay
+
+
+def apply_provider_overlay(
+    raw_bytes, overlay_bytes, *, expected_overlay_sha256, evidence_root
+):
+    """Return ``(effective_document, receipt)``; a matching digest is not readiness.
+
+    The caller supplies the independently approved exact overlay digest. Evidence
+    files are read locally beneath evidence_root without following symlinks.
+    """
+    if (
+        not isinstance(raw_bytes, bytes)
+        or not isinstance(overlay_bytes, bytes)
+        or _hash(overlay_bytes) != expected_overlay_sha256
+    ):
+        raise ValueError("Expected reviewed overlay SHA256 mismatch or non-byte input")
+    document = json.loads(raw_bytes, object_pairs_hook=_pairs)
+    overlay = _overlay_fields(json.loads(overlay_bytes, object_pairs_hook=_pairs))
+    if (
+        overlay["version"] not in {1, 2}
+        or _hash(raw_bytes) != overlay["raw_source_sha256"]
+    ):
+        raise ValueError("Unsupported overlay version or raw source SHA256 mismatch")
+    validate_security(document)
+    effective = copy.deepcopy(document)
+    evidence = _evidence(overlay["evidence_files"], evidence_root)
+    unknown = _apply(effective, overlay, evidence)
+    encoded = (
+        json.dumps(
+            effective, sort_keys=True, indent=2, ensure_ascii=True, allow_nan=False
+        )
+        + "\n"
+    ).encode()
+    if _hash(encoded) != overlay["effective_source_sha256"]:
+        raise ValueError("Effective source SHA256 mismatch")
+    receipt = {
+        **overlay,
+        "overlay_sha256": _hash(overlay_bytes),
+        "remaining_unknown_operation_ids": unknown,
+        "ready": False,
+        "transport_parity_verified": False,
+        "live_verified": False,
+    }
+    return effective, receipt