eraflow 0.1.0a1__py3-none-any.whl

eraflow/__init__.py

@@ -0,0 +1,39 @@
+# coding=utf-8
+"""ERAF 协议的 Python 接入 SDK；导入不启动任务或访问网络。"""
+
+from ._version import __version__
+from .materials import (
+    ConsumerTarget,
+    CredentialBytes,
+    ERAFIdentityMaterialError,
+    NoPackageError,
+    TrustedArtifact,
+)
+from .provider import (
+    Admission,
+    HTTPRequestBytes,
+    Provider,
+    ProviderAccessError,
+    ProviderOperation,
+    UnavailableProvider,
+)
+from .runtime import ExternalRuntime, ExternalStartupError, MaterialView, prepare_external_target
+
+__all__ = [
+    "__version__",
+    "ConsumerTarget",
+    "CredentialBytes",
+    "ERAFIdentityMaterialError",
+    "NoPackageError",
+    "TrustedArtifact",
+    "Admission",
+    "HTTPRequestBytes",
+    "Provider",
+    "ProviderAccessError",
+    "ProviderOperation",
+    "UnavailableProvider",
+    "ExternalRuntime",
+    "MaterialView",
+    "ExternalStartupError",
+    "prepare_external_target",
+]

eraflow/_version.py

@@ -0,0 +1,4 @@
+# coding=utf-8
+"""发行版本的唯一来源。"""
+
+__version__ = "0.1.0a1"

eraflow/flask.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+# coding=utf-8
+# CommonLib
+
+"""External 公共 Flask 接线：安装入口、请求保护装饰器与 /external/status 路由。
+
+来源实现：v1.1.0；发行版本统一由 eraflow._version 提供。
+Updated: 2026-10-23
+变更记录：
+    v1.1.0 | 2026-10-23 | HTTP 接纳使用服务器原始事实和原请求预算，有限缓冲正文并将同一字节交给业务；拒绝编码及流式入口。
+    v1.0.4 | 2026-10-20 | 公共文件简化为 provider_api/provider_lib，更新唯一引用；业务行为、协议与鉴权不变。
+    v1.0.3 | 2026-10-20 | 公共文件迁入 External 子目录，固定新引用和服务根定位；协议、鉴权与生命周期不变。
+    v1.0.2 | 2026-10-20 | 唯一安装入口承接无可信制品的公共失败 Status，保留管理员预算和保护拒绝链
+    v1.0.1 | 2026-10-19 | 仅 External 强制禁止缓存，统一脱敏 HTTPException，保留内部历史响应并拒绝异实例重复安装
+    v1.0.0 | 2026-10-19 | 首版：install_provider 向 app.extensions['commonlib.external']
+                          注册生命周期（serv_process 监听前 start/退出 stop）；
+                          ExternalHTTP.protect(operation_id) 静态操作保护装饰器——
+                          请求入口建统一单调 deadline、消费 commonlib.socket_facts、
+                          解析唯一 Authorization（Bearer/DPoP）与 Edge 证明头、调用
+                          Provider.authorize 一次内省并保存请求级 Admission；
+                          read 操作在有限响应发出前自动复核，write 操作由业务在最后
+                          可拒绝点显式 Admission.recheck()；/external/status 复用既有
+                          管理员 Bearer guard（libs.token_auth_lib），只读、no-store、
+                          拒绝 query/body/Transfer-Encoding，HEAD 同鉴权、OPTIONS 不给
+                          详情、清除 CORS；错误响应稳定脱敏，不回显 Token/异常正文
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import time
+import uuid
+from functools import wraps
+from typing import Any, Callable, Optional
+
+from flask import Blueprint, Response, g, jsonify, request
+from werkzeug.exceptions import HTTPException
+
+from .provider import (
+    MAX_HTTP_BODY_BYTES,
+    STATUS_TOTAL_TIMEOUT,
+    Admission,
+    HTTPRequestBytes,
+    Provider,
+    ProviderAccessError,
+    UnavailableProvider,
+    _http_request_fields,
+)
+
+_AUTHORIZATION_PATTERN = re.compile(r"(Bearer|DPoP) ([\x21-\x2b\x2d-\x7e]+)")
+_ERROR_STATUS = {"authentication": 401, "authorization": 403, "dependency": 503}
+_ERROR_MESSAGE = {
+    "authentication": "外部请求认证未通过",
+    "authorization": "外部请求无操作权限",
+    "dependency": "外部依赖暂不可用",
+}
+
+
+def _request_id() -> Any:
+    return uuid.uuid4().hex
+
+
+def _error_response(status: Any, code: Any, correlation_id: Any) -> Any:
+    response = jsonify({"code": code, "message": "请求未能完成", "request_id": correlation_id})
+    response.status_code = status
+    response.headers["X-Request-Id"] = correlation_id
+    response.headers["Cache-Control"] = "no-store"
+    return response
+
+
+def _access_error_response(error: Any) -> Any:
+    status = _ERROR_STATUS.get(error.category, 503)
+    response = jsonify(
+        {
+            "code": "external_" + error.category,
+            "message": _ERROR_MESSAGE.get(error.category, "请求未能完成"),
+            "request_id": _request_id(),
+        }
+    )
+    response.status_code = status
+    if status == 401:
+        response.headers["WWW-Authenticate"] = "Bearer"
+    response.headers["Cache-Control"] = "no-store"
+    return response
+
+
+def _strip_external_cors(response: Any) -> Any:
+    """External 响应不保留全局历史 CORS 许可。"""
+    if request.path == "/external" or request.path.startswith("/external/"):
+        for name in (
+            "Access-Control-Allow-Origin",
+            "Access-Control-Allow-Headers",
+            "Access-Control-Allow-Methods",
+            "Access-Control-Allow-Credentials",
+            "Access-Control-Expose-Headers",
+            "Access-Control-Max-Age",
+        ):
+            response.headers.pop(name, None)
+        response.headers["Cache-Control"] = "no-store"
+    return response
+
+
+class ExternalHTTP(object):
+    """安装入口返回的请求保护面；只在受保护请求内暴露 Admission。"""
+
+    def __init__(self, app: Any, provider: Any) -> None:
+        self.app = app
+        self.provider = provider
+
+    @property
+    def admission(self) -> Admission:
+        """本请求本操作的不可变接纳上下文；未受保护请求/跨请求读取均失败。"""
+        admission = getattr(g, "external_admission", None)
+        if not isinstance(admission, Admission):
+            raise ProviderAccessError("dependency", "admission_missing")
+        return admission
+
+    def protect(self, operation_id: str) -> Callable[..., Any]:
+        operation = self.provider.operations.get(operation_id)
+        if operation is None:
+            raise ValueError("unknown external operation: %s" % operation_id)
+
+        def decorate(handler: Any) -> Any:
+            endpoint = handler.__name__
+
+            @wraps(handler)
+            def wrapped(*args: Any, **kwargs: Any) -> Any:
+                if request.endpoint is None or request.endpoint.rsplit(".", 1)[-1] != (
+                    operation.endpoint if operation.endpoint else endpoint
+                ):
+                    return _error_response(405, "method_not_allowed", _request_id())
+                if request.method not in operation.methods:
+                    return _error_response(405, "method_not_allowed", _request_id())
+                started = time.monotonic()
+                inbound = self.provider.inbound_seconds
+                deadline = started + inbound if inbound is not None else None
+                values = request.headers.getlist("Authorization")
+                match = _AUTHORIZATION_PATTERN.fullmatch(values[0]) if len(values) == 1 else None
+                if match is None or request.headers.getlist("DPoP"):
+                    return _access_error_response(
+                        ProviderAccessError("authentication", "malformed_token")
+                    )
+                scheme, token = match.groups()
+                attestation_values = request.headers.getlist("X-SMAI-Transport-Attestation")
+                attestation = attestation_values[0] if len(attestation_values) == 1 else None
+                if len(attestation_values) > 1:
+                    return _access_error_response(
+                        ProviderAccessError("authentication", "attestation_malformed")
+                    )
+                facts = request.environ.get("commonlib.socket_facts")
+                try:
+                    captured = None
+                    if type(facts) is dict and facts.get("tls") is False:
+                        raw = request.environ.get("commonlib.http_request_bytes")
+                        if (
+                            type(raw) is not dict
+                            or raw.get("input") is not request.environ["wsgi.input"]
+                            or raw.get("method") != request.method
+                            or raw.get("target") != facts.get("raw_target")
+                            or type(raw.get("started")) not in (int, float)
+                            or raw["started"] > started
+                            or deadline is None
+                            or "_cached_data" in request.__dict__
+                            or getattr(raw["input"], "position", 0) != 0
+                        ):
+                            raise ProviderAccessError("dependency", "socket_facts")
+                        deadline = min(deadline, raw["started"] + inbound)
+                        headers = raw["headers"]
+
+                        def values_for(name: Any) -> Any:
+                            return [v for k, v in headers if k.lower() == name]
+
+                        if (
+                            values_for("authorization") != values
+                            or values_for("x-smai-transport-attestation") != attestation_values
+                        ):
+                            raise ProviderAccessError("authentication", "attestation_malformed")
+                        # 先检查 framing，再在原预算内读取；不会等待未声明长度的流。
+                        lengths = values_for("content-length")
+                        if (
+                            len(lengths) > 1
+                            or lengths
+                            and not re.fullmatch("0|[1-9][0-9]*", lengths[0])
+                            or any(
+                                values_for(n)
+                                for n in (
+                                    "content-encoding",
+                                    "transfer-encoding",
+                                    "trailer",
+                                    "expect",
+                                )
+                            )
+                        ):
+                            raise ProviderAccessError("authentication", "attestation_claims")
+                        length = int(lengths[0]) if lengths else 0
+                        if length > MAX_HTTP_BODY_BYTES:
+                            raise ProviderAccessError("authentication", "attestation_claims")
+                        body = self.provider._bounded(lambda: raw["input"].read(length), deadline)
+                        if len(body) != length:
+                            raise ProviderAccessError("authentication", "attestation_claims")
+                        captured = HTTPRequestBytes(request.method, raw["target"], headers, body)
+                        _http_request_fields(captured)
+                        request._cached_data = body
+                        request.environ["wsgi.input"] = io.BytesIO(body)
+                        request.__dict__["stream"] = request.environ["wsgi.input"]
+                    admission = self.provider.authorize(
+                        facts,
+                        operation_id,
+                        scheme,
+                        token,
+                        request.method,
+                        attestation=attestation,
+                        deadline=deadline,
+                        **({"http_request": captured} if captured is not None else {}),
+                    )
+                    g.external_admission = admission
+                    result = handler(*args, **kwargs)
+                    if isinstance(result, Response):
+                        payload = result
+                    else:
+                        payload = jsonify(result)
+                    # 有限读响应发出前复核同次依据；写操作由业务最后可拒绝点显式复核。
+                    if operation.accept == "read":
+                        admission.recheck()
+                    return payload
+                except ProviderAccessError as error:
+                    return _access_error_response(error)
+                except HTTPException as error:
+                    return _error_response(
+                        error.code or 503, "external_request_failed", _request_id()
+                    )
+                except Exception:
+                    # 不记录异常链或请求正文；诊断按 request_id 关联。
+                    return _error_response(503, "external_dependency_unavailable", _request_id())
+
+            return wrapped
+
+        return decorate
+
+
+def _status_exception_response(error: Any) -> Any:
+    status = error.code if isinstance(error, HTTPException) else 503
+    description = (
+        error.description
+        if isinstance(error, HTTPException) and type(error.description) is dict
+        else {}
+    )
+    code = description.get("code")
+    if code not in ("00010", "00011", "00021"):
+        code = "00011" if status in (401, 403) else "00021"
+    message = description.get("msg") if status in (401, 403) else None
+    if message not in ("授权超时", "授权无效", "权限不足"):
+        message = "授权无效" if status in (401, 403) else "诊断请求失败"
+    return jsonify({"code": code, "msg": message, "data": {}}), status
+
+
+def _bounded_status(call: Any, deadline: Any) -> Any:
+    from gevent import Timeout
+
+    class _Expired(Exception):
+        pass
+
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        return jsonify({"code": "00021", "msg": "诊断请求失败", "data": {}}), 503
+    try:
+        with Timeout(remaining, _Expired()):
+            return call()
+    except _Expired:
+        return jsonify({"code": "00021", "msg": "诊断请求失败", "data": {}}), 503
+
+
+def install_provider(
+    app: Any,
+    provider: Any,
+    service_display: Optional[str] = None,
+    storage_check: Optional[Callable[..., Any]] = None,
+    admin_guard: Optional[Callable[..., Any]] = None,
+) -> ExternalHTTP:
+    """唯一安装入口：注册生命周期、Status 路由与保护边界；import 时不启动。
+
+    provider 为可信制品构造的 Provider 或准备失败的 UnavailableProvider；后者
+    仅保留诊断和拒绝接纳，不创建运行时。storage_check 为服务自有
+    必要持久层只读检查（返回 STORAGE_NOT_APPLICABLE 表示真实无持久层），
+    不从 ZIP/请求新增探测目标。admin_guard 为既有管理员 Bearer guard 装饰器
+    （必须由宿主显式传入；缺失拒绝安装）。安装幂等；构造失败由创建方清理。
+    """
+    if not callable(admin_guard):
+        raise ValueError("admin_guard must be an explicit administrator decorator")
+    if not isinstance(provider, (Provider, UnavailableProvider)):
+        raise ValueError("provider must be Provider or UnavailableProvider")
+    if service_display is not None and (
+        type(service_display) is not str
+        or re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,119}", service_display) is None
+    ):
+        raise ValueError("invalid external service display")
+    http = app.extensions.get("commonlib.external_http")
+    if http is not None:
+        if http.provider is not provider:
+            raise ValueError("external provider already installed")
+        return http
+    http = ExternalHTTP(app, provider)
+    app.extensions["commonlib.external_http"] = http
+    # serv_process 在监听前 start、退出 finally stop；此处不重复注册 atexit。
+    app.extensions["commonlib.external"] = provider
+
+    status_api = Blueprint("commonlib_external_status", __name__)
+
+    @status_api.route("/external/status", methods=["GET"], provide_automatic_options=False)
+    def external_status() -> Any:
+        deadline = time.monotonic() + STATUS_TOTAL_TIMEOUT
+
+        def invoke() -> Any:
+            if (
+                request.args
+                or request.content_length not in (None, 0)
+                or request.environ.get("HTTP_TRANSFER_ENCODING")
+            ):
+                from flask import abort
+
+                abort(400, {"code": "00021"})
+            data = provider.collect_status(
+                request.environ.get("commonlib.socket_facts"),
+                storage_check,
+                deadline=deadline,
+                service_display=service_display,
+            )
+            response = jsonify({"code": "00000", "msg": "成功", "data": data})
+            response.headers["Cache-Control"] = "no-store"
+            return response
+
+        guard = admin_guard
+        try:
+            return _bounded_status(guard(invoke), deadline)
+        except HTTPException as error:
+            return _status_exception_response(error)
+        except Exception:
+            return _status_exception_response(Exception())
+
+    app.register_blueprint(status_api)
+
+    # 路由匹配失败、未加保护的 External 路由也不进入会回显正文的历史处理器。
+    handle_http_exception = app.handle_http_exception
+
+    def external_http_exception(error: Any) -> Any:
+        if request.path == "/external" or request.path.startswith("/external/"):
+            return _error_response(error.code or 503, "external_request_failed", _request_id())
+        return handle_http_exception(error)
+
+    app.handle_http_exception = external_http_exception
+
+    @app.after_request
+    def _commonlib_external_boundary(response: Any) -> Any:
+        return _strip_external_cors(response)
+
+    return http