blun-king-cli 9.1.597 → 9.1.600

package/standard-skills/translate-native/integrations/website_localization_cms_terminal_notification_receiver.py

@@ -30,11 +30,13 @@ PROCESSING_ACK_SCHEMA = "blun.cms-terminal-notification-processing-ack.v1"
 AUTH_SCHEMA = "blun.cms-source-terminal-notification-http-auth.v1"
 PRINCIPAL_SCHEMA = "blun.cms-source-terminal-notification-principal.v1"
 ERROR_SCHEMA = "blun.cms-source-terminal-notification-http-error.v1"
-API_SCHEMA = "blun.cms-terminal-receiver-api.v1"
-CAPABILITIES_SCHEMA = "blun.cms-terminal-receiver-capabilities.v1"
+API_SCHEMA = "blun.cms-terminal-receiver-api.v3"
+CAPABILITIES_SCHEMA = "blun.cms-terminal-receiver-capabilities.v3"
 CAPABILITIES_RESPONSE_SCHEMA = (
-    "blun.cms-terminal-receiver-capabilities-response.v1"
+    "blun.cms-terminal-receiver-capabilities-response.v3"
 )
+OPENAPI_RESPONSE_SCHEMA = "blun.cms-terminal-receiver-openapi-response.v1"
+OPENAPI_DOCUMENT_SCHEMA = "blun.cms-terminal-receiver-openapi.v2"
 HEALTH_RESPONSE_SCHEMA = "blun.cms-terminal-receiver-health.v1"
 HEALTH_RESPONSE_FIELDS = (
     "schema", "status", "runtime_state", "worker_state", "inbox_status",
@@ -45,16 +47,20 @@ WRITE_SCOPE = "terminal-notification:write"
 STATUS_SCOPE = "terminal-notification-status:read"
 READINESS_SCOPE = "terminal-notification-readiness:read"
 CAPABILITIES_SCOPE = "terminal-notification-capabilities:read"
+OPENAPI_SCOPE = "terminal-notification-openapi:read"
 HEALTH_SCOPE = "terminal-notification-health:read"
 DEFAULT_PATH = "/v1/localization/terminal-notifications"
 STATUS_PATH = DEFAULT_PATH + "/status"
 READINESS_PATH = DEFAULT_PATH + "/readiness"
 CAPABILITIES_PATH = DEFAULT_PATH + "/capabilities"
+OPENAPI_PATH = DEFAULT_PATH + "/openapi"
 HEALTH_PATH = DEFAULT_PATH + "/health"
+CAPABILITIES_PRECONDITION_HEADER = "X-Localization-Capabilities-SHA256"
 STATUS_REQUEST_SCHEMA = "blun.cms-terminal-receiver-status-request.v1"
 STATUS_RESPONSE_SCHEMA = "blun.cms-terminal-receiver-status-response.v1"
 READINESS_RESPONSE_SCHEMA = "blun.cms-terminal-receiver-readiness.v1"
 MAX_BODY_BYTES = 16_384
+MAX_RESPONSE_BYTES = 1_000_000
 MAX_HEADERS = 64
 MAX_HEADER_VALUE_LENGTH = 4_096
 TOKEN = re.compile(r"^[A-Za-z0-9_.:-]{1,256}$")
@@ -174,7 +180,7 @@ def _blocked(code: str, status: int) -> None:
     raise TerminalNotificationReceiverBlocked("notification_receiver." + code, status)
 
 
-def _canonical(value: Any) -> bytes:
+def _canonical(value: Any, *, max_bytes: int = MAX_BODY_BYTES) -> bytes:
     try:
         result = json.dumps(
             value, ensure_ascii=False, allow_nan=False, sort_keys=True,
@@ -182,7 +188,7 @@ def _canonical(value: Any) -> bytes:
         ).encode("utf-8")
     except (TypeError, ValueError, RecursionError):
         _blocked("request_invalid", 400)
-    if not result or len(result) > MAX_BODY_BYTES:
+    if not result or len(result) > max_bytes:
         _blocked("request_invalid", 400)
     return result
 
@@ -359,6 +365,19 @@ def capabilities_payload(notification_path: str = DEFAULT_PATH) -> dict[str, Any
             ],
             "success_status": 200,
         },
+        "openapi": {
+            "method": "GET",
+            "path": OPENAPI_PATH,
+            "scope": OPENAPI_SCOPE,
+            "request_schema": None,
+            "request_fields": [],
+            "response_schema": OPENAPI_RESPONSE_SCHEMA,
+            "response_fields": [
+                "schema", "openapi", "openapi_sha256",
+                "capabilities_sha256",
+            ],
+            "success_status": 200,
+        },
         "readiness": {
             "method": "GET",
             "path": READINESS_PATH,
@@ -393,12 +412,13 @@ def capabilities_payload(notification_path: str = DEFAULT_PATH) -> dict[str, Any
     if (
         not isinstance(notification_path, str)
         or notification_path in {
-            STATUS_PATH, READINESS_PATH, CAPABILITIES_PATH, HEALTH_PATH,
+            STATUS_PATH, READINESS_PATH, CAPABILITIES_PATH, OPENAPI_PATH,
+            HEALTH_PATH,
         }
         or len({
             WRITE_SCOPE, STATUS_SCOPE, READINESS_SCOPE, CAPABILITIES_SCOPE,
-            HEALTH_SCOPE,
-        }) != 5
+            OPENAPI_SCOPE, HEALTH_SCOPE,
+        }) != 6
     ):
         _blocked("capabilities_invalid", 503)
     operations = {
@@ -422,14 +442,21 @@ def capabilities_payload(notification_path: str = DEFAULT_PATH) -> dict[str, Any
             "success_status": 200,
         },
     }
+    for name, operation in operations.items():
+        operation["capabilities_precondition_header"] = (
+            None if name == "capabilities"
+            else CAPABILITIES_PRECONDITION_HEADER
+        )
     capabilities = {
         "schema": CAPABILITIES_SCHEMA,
         "api_schema": API_SCHEMA,
         "authentication_request_schema": AUTH_SCHEMA,
         "principal_schema": PRINCIPAL_SCHEMA,
         "error_schema": ERROR_SCHEMA,
+        "openapi_document_schema": OPENAPI_DOCUMENT_SCHEMA,
         "limits": {
             "max_body_bytes": MAX_BODY_BYTES,
+            "max_response_bytes": MAX_RESPONSE_BYTES,
             "max_headers": MAX_HEADERS,
             "max_header_value_bytes": MAX_HEADER_VALUE_LENGTH,
             "processing_max_attempts_min": 1,
@@ -438,10 +465,14 @@ def capabilities_payload(notification_path: str = DEFAULT_PATH) -> dict[str, Any
         "processing_statuses": list(PROCESSING_STATUSES),
         "terminal_statuses": sorted(TERMINAL_STATUSES),
         "operations": operations,
+        "semantics": {
+            "non_discovery_operations_require_exact_capability_precondition": True,
+        },
     }
     try:
         if set(operations) != {
-            "capabilities", "health", "notification", "readiness", "status",
+            "capabilities", "health", "notification", "openapi",
+            "readiness", "status",
         }:
             raise ValueError
         if set(NOTIFICATION_FIELDS) != set(
@@ -1338,7 +1369,8 @@ class CMSTerminalNotificationReceiverApplication:
             or "#" in path
             or len(path) > 256
             or path in {
-                STATUS_PATH, READINESS_PATH, CAPABILITIES_PATH, HEALTH_PATH,
+                STATUS_PATH, READINESS_PATH, CAPABILITIES_PATH, OPENAPI_PATH,
+                HEALTH_PATH,
             }
         ):
             raise ValueError("path is invalid")
@@ -1379,12 +1411,14 @@ class CMSTerminalNotificationReceiverApplication:
 
     @staticmethod
     def _send(start_response: Callable[..., Any], status: int, value: Any):
-        body = _canonical(value)
+        body = _canonical(value, max_bytes=MAX_RESPONSE_BYTES)
         phrases = {
             200: "OK", 400: "Bad Request", 401: "Unauthorized",
             403: "Forbidden", 404: "Not Found", 405: "Method Not Allowed",
-            409: "Conflict", 411: "Length Required", 413: "Content Too Large",
-            415: "Unsupported Media Type", 503: "Service Unavailable",
+            409: "Conflict", 411: "Length Required",
+            412: "Precondition Failed", 413: "Content Too Large",
+            415: "Unsupported Media Type", 428: "Precondition Required",
+            503: "Service Unavailable",
         }
         start_response(f"{status} {phrases[status]}", (
             ("Content-Type", "application/json; charset=utf-8"),
@@ -1445,12 +1479,21 @@ class CMSTerminalNotificationReceiverApplication:
                 "event_id": payload["event_id"],
                 "site_id": payload["site_id"],
                 "body_sha256": body_sha256,
+                "capabilities_sha256": headers.get(
+                    "x-localization-capabilities-sha256"
+                ),
             }
             try:
                 principal = self.authenticate(dict(request), dict(headers))
             except Exception:
                 _blocked("authentication_unavailable", 503)
             _principal(principal, payload["site_id"])
+            expected_capabilities = capabilities_payload(self.path)["sha256"]
+            supplied_capabilities = request["capabilities_sha256"]
+            if supplied_capabilities is None:
+                _blocked("capabilities_precondition_required", 428)
+            if supplied_capabilities != expected_capabilities:
+                _blocked("capabilities_precondition_failed", 412)
             acknowledgement = self.inbox.accept(
                 payload, body, body_sha256, now=self.clock(),
             )

package/standard-skills/translate-native/integrations/website_localization_cms_terminal_notification_receiver_openapi.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Canonical OpenAPI 3.1 profile for the terminal-notification receiver."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+
+DOCUMENT_SCHEMA = "blun.cms-terminal-receiver-openapi.v2"
+RESPONSE_SCHEMA = "blun.cms-terminal-receiver-openapi-response.v1"
+
+
+def _canonical(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, allow_nan=False, sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _ref(name: str) -> dict[str, str]:
+    return {"$ref": "#/components/schemas/" + name}
+
+
+def _object(
+    properties: Mapping[str, Any], *, optional: tuple[str, ...] = (),
+) -> dict[str, Any]:
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": sorted(set(properties) - set(optional)),
+        "properties": dict(properties),
+    }
+
+
+def _exact(value: Any) -> dict[str, Any]:
+    if isinstance(value, Mapping):
+        return _object({str(key): _exact(item) for key, item in value.items()})
+    if value is None:
+        return {"type": "null"}
+    if isinstance(value, bool):
+        return {"type": "boolean", "const": value}
+    if isinstance(value, int):
+        return {"type": "integer", "const": value}
+    if isinstance(value, str):
+        return {"type": "string", "const": value}
+    if isinstance(value, (list, tuple)):
+        items = [_exact(item) for item in value]
+        return {
+            "type": "array", "prefixItems": items, "items": False,
+            "minItems": len(items), "maxItems": len(items),
+        }
+    raise TypeError("unsupported exact capability value")
+
+
+def _error_response(status: int, codes: tuple[str, ...]) -> dict[str, Any]:
+    return {
+        "description": "Fail-closed, content-free receiver error.",
+        "content": {"application/json": {"schema": _object({
+            "schema": {"const": "blun.cms-source-terminal-notification-http-error.v1"},
+            "status": {"const": "BLOCK"},
+            "error_code": {"type": "string", "enum": list(codes)},
+        })}},
+        "x-error-codes": list(codes),
+        "x-http-status": status,
+    }
+
+
+_COMMON = {
+    400: (
+        "notification_receiver.body_invalid",
+        "notification_receiver.framing_invalid",
+        "notification_receiver.headers_invalid",
+        "notification_receiver.https_required",
+        "notification_receiver.query_rejected",
+    ),
+    401: ("notification_receiver.authentication_failed",),
+    403: ("notification_receiver.authorization_failed",),
+    405: ("notification_receiver.method_not_allowed",),
+    503: (
+        "notification_receiver.authentication_unavailable",
+        "notification_receiver.capabilities_invalid",
+        "notification_receiver.internal",
+        "notification_receiver.runtime_unavailable",
+    ),
+}
+
+
+def _errors(name: str) -> dict[int, tuple[str, ...]]:
+    result = {status: tuple(codes) for status, codes in _COMMON.items()}
+    if name != "capabilities":
+        result[412] = ("notification_receiver.capabilities_precondition_failed",)
+        result[428] = ("notification_receiver.capabilities_precondition_required",)
+    if name in {"capabilities", "health", "openapi", "readiness"}:
+        result[415] = ("notification_receiver.content_type",)
+    if name == "health":
+        result[503] += ("notification_receiver.health_invalid",)
+    if name == "notification":
+        result[400] += (
+            "notification_receiver.canonical_body_required",
+            "notification_receiver.header_binding_invalid",
+            "notification_receiver.json_invalid",
+            "notification_receiver.request_invalid",
+        )
+        result[409] = ("notification_receiver.idempotency_collision",)
+        result[411] = ("notification_receiver.content_length_required",)
+        result[413] = ("notification_receiver.body_too_large",)
+        result[415] = ("notification_receiver.content_type",)
+        result[503] += (
+            "notification_receiver.clock_invalid",
+            "notification_receiver.database_unsafe",
+            "notification_receiver.foreign_process",
+            "notification_receiver.integrity_failed",
+            "notification_receiver.schema_altered",
+            "notification_receiver.storage_unavailable",
+            "notification_receiver.stored_binding_invalid",
+            "notification_receiver.transaction_nested",
+        )
+    if name == "status":
+        result[400] += (
+            "notification_receiver.header_binding_invalid",
+            "notification_receiver.json_invalid",
+            "notification_receiver.request_invalid",
+        )
+        result[404] = ("notification_receiver.not_found",)
+        result[411] = ("notification_receiver.content_length_required",)
+        result[413] = ("notification_receiver.body_too_large",)
+        result[415] = ("notification_receiver.content_type",)
+    return {status: tuple(sorted(set(codes))) for status, codes in result.items()}
+
+
+def _operation(
+    name: str, contract: Mapping[str, Any], *, response: str,
+    request: str | None = None, degraded: bool = False,
+) -> dict[str, Any]:
+    responses: dict[str, Any] = {
+        str(contract["success_status"]): {
+            "description": "Exact validated content-free response.",
+            "content": {"application/json": {"schema": _ref(response)}},
+        },
+    }
+    for status, codes in _errors(name).items():
+        error = _error_response(status, codes)
+        if degraded and status == 503:
+            error["content"]["application/json"]["schema"] = {
+                "oneOf": [_ref(response), error["content"]["application/json"]["schema"]],
+            }
+        responses[str(status)] = error
+    operation: dict[str, Any] = {
+        "operationId": {
+            "capabilities": "discoverTerminalReceiverCapabilities",
+            "health": "readTerminalReceiverHealth",
+            "notification": "acceptTerminalNotification",
+            "openapi": "readTerminalReceiverOpenApi",
+            "readiness": "readTerminalReceiverReadiness",
+            "status": "readTerminalNotificationStatus",
+        }[name],
+        "security": [{"hostAuthentication": []}],
+        "x-authentication-scope": contract["scope"],
+        "responses": dict(sorted(responses.items(), key=lambda item: int(item[0]))),
+    }
+    if request is not None:
+        operation["requestBody"] = {
+            "required": True,
+            "content": {"application/json": {"schema": _ref(request)}},
+        }
+    parameters = []
+    if name != "capabilities":
+        parameters.append({
+            "name": contract["capabilities_precondition_header"],
+            "in": "header", "required": True, "schema": _ref("Sha256"),
+        })
+    if name == "notification":
+        parameters.extend([
+            {"name": "Idempotency-Key", "in": "header", "required": True,
+             "schema": _ref("NotificationId")},
+            {"name": "X-Localization-Terminal-Notification-Id", "in": "header",
+             "required": True, "schema": _ref("NotificationId")},
+            {"name": "X-Localization-Terminal-Notification-Sha256", "in": "header",
+             "required": True, "schema": _ref("Sha256")},
+        ])
+    elif name == "status":
+        parameters.append({
+            "name": "X-Localization-Terminal-Status-SHA256", "in": "header",
+            "required": True, "schema": _ref("Sha256"),
+        })
+    if parameters:
+        operation["parameters"] = parameters
+    return operation
+
+
+def build_document(capabilities: Mapping[str, Any]) -> dict[str, Any]:
+    """Build the origin-free document for one exact capability generation."""
+    operations = capabilities["operations"]
+    sha256 = {"type": "string", "pattern": "^[a-f0-9]{64}$"}
+    token = {"type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,256}$"}
+    nullable_time = {"oneOf": [{"type": "number", "minimum": 0}, {"type": "null"}]}
+    nullable_error = {"oneOf": [_ref("ErrorCode"), {"type": "null"}]}
+    count = {"type": "integer", "minimum": 0}
+    processing_statuses = capabilities["processing_statuses"]
+    terminal_statuses = capabilities["terminal_statuses"]
+    notification = _object({
+        "schema": {"const": operations["notification"]["request_schema"]},
+        "notification_id": _ref("NotificationId"),
+        "event_id": _ref("Token"), "site_id": _ref("Token"),
+        "plan_id": _ref("Token"), "website_version": _ref("Token"),
+        "source_sequence": {"type": "integer", "minimum": 1},
+        "job_count": {"type": "integer", "minimum": 1},
+        "change_sha256": _ref("Sha256"),
+        "lifecycle_binding_sha256": _ref("Sha256"),
+        "terminal_status": {"type": "string", "enum": terminal_statuses},
+        "lifecycle_sha256": {"oneOf": [_ref("Sha256"), {"type": "null"}]},
+    })
+    notification["allOf"] = [{
+        "if": {"properties": {"terminal_status": {"enum": ["cancelled", "superseded"]}}},
+        "then": {"properties": {"lifecycle_sha256": {"type": "null"}}},
+        "else": {"properties": {"lifecycle_sha256": _ref("Sha256")}},
+    }]
+    status_response = _object({
+        "schema": {"const": operations["status"]["response_schema"]},
+        "notification_id": _ref("NotificationId"),
+        "event_id": _ref("Token"), "site_id": _ref("Token"),
+        "terminal_status": {"type": "string", "enum": terminal_statuses},
+        "notification_sha256": _ref("Sha256"),
+        "processing_status": {"type": "string", "enum": processing_statuses},
+        "attempts": {"type": "integer", "minimum": 0, "maximum": 20},
+        "max_attempts": {"type": "integer", "minimum": 1, "maximum": 20},
+        "next_attempt_at": {"type": "number", "minimum": 0},
+        "lease_expires_at": nullable_time, "lease_expired": {"type": "boolean"},
+        "last_error_code": nullable_error, "processed_at": nullable_time,
+        "capabilities_sha256": {"const": capabilities["sha256"]},
+    })
+    count_properties = {name: count for name in processing_statuses}
+    health = _object({
+        "schema": {"const": operations["health"]["response_schema"]},
+        "status": {"type": "string", "enum": ["ok", "blocked"]},
+        "runtime_state": {"const": "open"},
+        "worker_state": {"type": "string", "enum": [
+            "unmanaged", "starting", "running", "stopping", "stopped", "failed",
+        ]},
+        "inbox_status": {"type": "string", "enum": ["ok", "blocked"]},
+        "received": {"oneOf": [count, {"type": "null"}]},
+        "processing_counts": {"oneOf": [_object(count_properties), {"type": "null"}]},
+        "processing_due": {"oneOf": [count, {"type": "null"}]},
+        "expired_leases": {"oneOf": [count, {"type": "null"}]},
+        "failed": {"oneOf": [count, {"type": "null"}]},
+        "error_code": nullable_error,
+        "capabilities_sha256": {"const": capabilities["sha256"]},
+    })
+    readiness = _object({
+        "schema": {"const": operations["readiness"]["response_schema"]},
+        "status": {"type": "string", "enum": ["ready", "not_ready"]},
+        "worker_state": {"type": "string", "enum": [
+            "unmanaged", "running", "stopping", "stopped", "failed", "closed",
+        ]},
+        "inbox_status": {"oneOf": [
+            {"type": "string", "enum": ["ok", "blocked"]}, {"type": "null"},
+        ]},
+        "error_code": nullable_error,
+        "capabilities_sha256": {"const": capabilities["sha256"]},
+    })
+    schemas = {
+        "Sha256": sha256, "Token": token,
+        "NotificationId": {"type": "string", "pattern": "^terminal-[a-f0-9]{64}$"},
+        "ErrorCode": {"type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,127}$"},
+        "Capabilities": {**_exact(capabilities), "x-capabilities-sha256": capabilities["sha256"]},
+        "CapabilitiesResponse": _object({
+            "schema": {"const": operations["capabilities"]["response_schema"]},
+            "capabilities": _ref("Capabilities"),
+        }),
+        "TerminalNotification": notification,
+        "NotificationAck": _object({
+            "schema": {"const": operations["notification"]["response_schema"]},
+            "notification_id": _ref("NotificationId"), "event_id": _ref("Token"),
+            "site_id": _ref("Token"), "status": {"const": "accepted"},
+            "notification_sha256": _ref("Sha256"),
+        }),
+        "StatusRequest": _object({
+            "schema": {"const": operations["status"]["request_schema"]},
+            "event_id": _ref("Token"), "site_id": _ref("Token"),
+        }),
+        "StatusResponse": status_response,
+        "HealthResponse": health,
+        "ReadinessResponse": readiness,
+        "OpenApiResponse": _object({
+            "schema": {"const": RESPONSE_SCHEMA}, "openapi": {"type": "object"},
+            "openapi_sha256": _ref("Sha256"),
+            "capabilities_sha256": {"const": capabilities["sha256"]},
+        }),
+    }
+    paths = {}
+    definitions = {
+        "capabilities": (None, "CapabilitiesResponse", False),
+        "health": (None, "HealthResponse", True),
+        "notification": ("TerminalNotification", "NotificationAck", False),
+        "openapi": (None, "OpenApiResponse", False),
+        "readiness": (None, "ReadinessResponse", True),
+        "status": ("StatusRequest", "StatusResponse", False),
+    }
+    for name, (request, response, degraded) in definitions.items():
+        contract = operations[name]
+        paths[contract["path"]] = {
+            contract["method"].lower(): _operation(
+                name, contract, request=request, response=response, degraded=degraded,
+            ),
+        }
+    return {
+        "openapi": "3.1.0",
+        "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+        "info": {
+            "title": "CMS Terminal Notification Receiver API",
+            "version": capabilities["api_schema"],
+            "description": (
+                "Provider-neutral, fail-closed terminal callback receiver. "
+                "Acknowledgement means durable intake only."
+            ),
+        },
+        "paths": dict(sorted(paths.items())),
+        "components": {
+            "securitySchemes": {"hostAuthentication": {
+                "type": "apiKey", "in": "header", "name": "Authorization",
+                "x-host-defined": True,
+            }},
+            "schemas": schemas,
+        },
+        "x-schema": DOCUMENT_SCHEMA,
+        "x-capabilities-sha256": capabilities["sha256"],
+        "x-content-free-responses": True,
+        "x-servers-omitted-intentionally": True,
+    }
+
+
+def document_sha256(document: Mapping[str, Any]) -> str:
+    return hashlib.sha256(_canonical(dict(document))).hexdigest()

package/standard-skills/translate-native/integrations/website_localization_cms_terminal_notification_receiver_runtime.py

@@ -35,6 +35,12 @@ _RECEIVER = _load_module(
     / "integrations"
     / "website_localization_cms_terminal_notification_receiver.py",
 )
+_OPENAPI = _load_module(
+    "blun_website_localization_terminal_receiver_openapi_runtime_dependency",
+    _ROOT
+    / "integrations"
+    / "website_localization_cms_terminal_notification_receiver_openapi.py",
+)
 
 
 class DurableTerminalReceiverRuntimeBlocked(RuntimeError):
@@ -313,7 +319,8 @@ class DurableTerminalNotificationReceiverRuntime:
                 self._require_open()
                 if isinstance(environ, Mapping) and environ.get("PATH_INFO") in {
                     _RECEIVER.STATUS_PATH, _RECEIVER.READINESS_PATH,
-                    _RECEIVER.CAPABILITIES_PATH, _RECEIVER.HEALTH_PATH,
+                    _RECEIVER.CAPABILITIES_PATH, _RECEIVER.OPENAPI_PATH,
+                    _RECEIVER.HEALTH_PATH,
                 }:
                     return self._control_request(environ, start_response)
                 self.require_worker_ready()
@@ -345,6 +352,10 @@ class DurableTerminalNotificationReceiverRuntime:
                 return self._capabilities_request(
                     environ, headers, start_response,
                 )
+            if path == _RECEIVER.OPENAPI_PATH:
+                return self._openapi_request(
+                    environ, headers, start_response,
+                )
             if path == _RECEIVER.HEALTH_PATH:
                 return self._health_request(environ, headers, start_response)
             if path == _RECEIVER.READINESS_PATH:
@@ -370,6 +381,10 @@ class DurableTerminalNotificationReceiverRuntime:
         site_id: str | None,
         scope: str,
     ) -> None:
+        if request["path"] != _RECEIVER.CAPABILITIES_PATH:
+            request["capabilities_sha256"] = headers.get(
+                "x-localization-capabilities-sha256"
+            )
         try:
             principal = self.application.authenticate(
                 dict(request), dict(headers)
@@ -377,6 +392,19 @@ class DurableTerminalNotificationReceiverRuntime:
         except Exception:
             _RECEIVER._blocked("authentication_unavailable", 503)
         _RECEIVER._principal(principal, site_id, scope)
+        if request["path"] != _RECEIVER.CAPABILITIES_PATH:
+            supplied = request["capabilities_sha256"]
+            expected = _RECEIVER.capabilities_payload(
+                self.application.path
+            )["sha256"]
+            if supplied is None:
+                _RECEIVER._blocked(
+                    "capabilities_precondition_required", 428
+                )
+            if supplied != expected:
+                _RECEIVER._blocked(
+                    "capabilities_precondition_failed", 412
+                )
 
     def _capabilities_request(
         self,
@@ -440,6 +468,43 @@ class DurableTerminalNotificationReceiverRuntime:
         status = 200 if report["status"] == "ready" else 503
         return self.application._send(start_response, status, report)
 
+    def _openapi_request(
+        self,
+        environ: Mapping[str, Any],
+        headers: dict[str, str],
+        start_response: Callable[..., Any],
+    ):
+        if environ.get("REQUEST_METHOD") != "GET":
+            _RECEIVER._blocked("method_not_allowed", 405)
+        if headers.get("content-length") not in {None, "0"}:
+            _RECEIVER._blocked("body_invalid", 400)
+        if "content-type" in headers:
+            _RECEIVER._blocked("content_type", 415)
+        body_sha256 = hashlib.sha256(b"").hexdigest()
+        request = {
+            "schema": _RECEIVER.AUTH_SCHEMA,
+            "method": "GET",
+            "origin": self.application.origin,
+            "path": _RECEIVER.OPENAPI_PATH,
+            "body_sha256": body_sha256,
+        }
+        self._authenticate_control(
+            request, headers, None, _RECEIVER.OPENAPI_SCOPE,
+        )
+        capabilities = _RECEIVER.capabilities_payload(self.application.path)
+        document = _OPENAPI.build_document(capabilities)
+        if (
+            document.get("x-schema") != capabilities["openapi_document_schema"]
+            or document.get("x-capabilities-sha256") != capabilities["sha256"]
+        ):
+            _RECEIVER._blocked("capabilities_invalid", 503)
+        return self.application._send(start_response, 200, {
+            "schema": _RECEIVER.OPENAPI_RESPONSE_SCHEMA,
+            "openapi": document,
+            "openapi_sha256": _OPENAPI.document_sha256(document),
+            "capabilities_sha256": capabilities["sha256"],
+        })
+
     def _health_request(
         self,
         environ: Mapping[str, Any],