eraflow 0.1.0a1__tar.gz

eraflow-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deepaint-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eraflow-0.1.0a1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md LICENSE NOTICE pyproject.toml
+recursive-include src/eraflow *.py py.typed
+prune docs
+prune test
+prune tmp
+prune .venv
+prune .github
+global-exclude *.pyc __pycache__

eraflow-0.1.0a1/NOTICE

@@ -0,0 +1,4 @@
+eraflow 采用 MIT License，完整许可见 LICENSE；用户于 2026-10-30 明确授权采用 MIT。
+ERAF 公共实现提取自 CommonLib，提交 6345822245da9df10f71e4f2b3e7fcdb954eb9b3，保留源码中的原始来源声明。
+Copyright (c) 2026 deepaint-ai
+cryptography、gevent、Flask、Werkzeug 是独立依赖，不复制其实现；各自许可证不被本声明替换。

eraflow-0.1.0a1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.1
+Name: eraflow
+Version: 0.1.0a1
+Summary: ERAF 协议的 Python 接入 SDK，统一提供身份与凭据自动安装、轮换恢复、Edge 请求验签、实时鉴权及运行状态诊断，简化服务的 External API 接入。
+License: MIT
+Project-URL: Repository, https://github.com/deepaint-ai/eraflow
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: flask
+Provides-Extra: dev
+License-File: LICENSE
+License-File: NOTICE
+
+# eraflow
+
+ERAF 协议的 Python 接入 SDK，统一提供身份与凭据自动安装、轮换恢复、Edge 请求验签、实时鉴权及运行状态诊断，简化服务的 External API 接入。
+
+当前发行候选为 0.1.0a1（Alpha 预发布），供隔离验证与下游接入评估；不代表生产接线已完成。最低 Python 3.7，完整文件安装仅面向 Windows/Linux；macOS 未支持。纯 Python wheel 标签不代表所有平台安装语义可用。
+
+```python
+from eraflow import Provider, ProviderOperation, prepare_external_target
+from eraflow.flask import install_provider
+# service_root、静态身份、UAC 配置与安全回调由宿主明确提供。
+```
+
+核心不隐式导入 Flask，不在导入时启动任务或联网。管理员保护、真实 socket/原始请求事实、共享防重放、领域授权及写操作最终复核均须由宿主接线。
+
+源码来自固定 CommonLib 提交，保留材料协议和 data/.cache 布局。参见源码仓 docs/README.md 的接入、迁移、验证和发布说明。采用 MIT License，见 LICENSE；来源及依赖声明见 NOTICE。

eraflow-0.1.0a1/README.md

@@ -0,0 +1,15 @@
+# eraflow
+
+ERAF 协议的 Python 接入 SDK，统一提供身份与凭据自动安装、轮换恢复、Edge 请求验签、实时鉴权及运行状态诊断，简化服务的 External API 接入。
+
+当前发行候选为 0.1.0a1（Alpha 预发布），供隔离验证与下游接入评估；不代表生产接线已完成。最低 Python 3.7，完整文件安装仅面向 Windows/Linux；macOS 未支持。纯 Python wheel 标签不代表所有平台安装语义可用。
+
+```python
+from eraflow import Provider, ProviderOperation, prepare_external_target
+from eraflow.flask import install_provider
+# service_root、静态身份、UAC 配置与安全回调由宿主明确提供。
+```
+
+核心不隐式导入 Flask，不在导入时启动任务或联网。管理员保护、真实 socket/原始请求事实、共享防重放、领域授权及写操作最终复核均须由宿主接线。
+
+源码来自固定 CommonLib 提交，保留材料协议和 data/.cache 布局。参见源码仓 docs/README.md 的接入、迁移、验证和发布说明。采用 MIT License，见 LICENSE；来源及依赖声明见 NOTICE。

eraflow-0.1.0a1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=67.8", "wheel>=0.42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eraflow"
+dynamic = ["version"]
+description = "ERAF 协议的 Python 接入 SDK，统一提供身份与凭据自动安装、轮换恢复、Edge 请求验签、实时鉴权及运行状态诊断，简化服务的 External API 接入。"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.7"
+dependencies = ["cryptography>=43.0.3,<47", "gevent>=22.10.2,<27", "requests>=2.20,<3"]
+classifiers = ["License :: OSI Approved :: MIT License", "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Operating System :: Microsoft :: Windows", "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3 :: Only"]
+
+[project.urls]
+Repository = "https://github.com/deepaint-ai/eraflow"
+
+[project.optional-dependencies]
+flask = ["Flask>=2.2.5,<4", "Werkzeug>=2.2.3,<4"]
+dev = ["build==0.10.0; python_version < '3.8'", "build>=1,<2; python_version >= '3.8'", "mypy==1.4.1", "pytest==7.4.4; python_version < '3.8'", "pytest>=8,<10; python_version >= '3.8'", "ruff==0.8.6", "types-requests==2.31.0.6", "jsonschema>=4.17,<5", "setuptools>=67.8", "wheel>=0.42", "SQLAlchemy>=1.4,<2", "PyJWT>=2,<3", "arrow<1", "redis==4.5.5", "pywin32>=300; sys_platform == 'win32'"]
+
+[tool.setuptools.dynamic]
+version = {attr = "eraflow._version.__version__"}
+[tool.setuptools.packages.find]
+where = ["src"]
+[tool.setuptools.package-data]
+eraflow = ["py.typed"]
+[tool.setuptools]
+license-files = ["LICENSE", "NOTICE"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+addopts = "-ra -p no:cacheprovider --basetemp=tmp/pytest"
+
+[tool.ruff]
+target-version = "py37"
+line-length = 100
+cache-dir = "tmp/ruff-cache"
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.mypy]
+python_version = "3.7"
+files = ["src/eraflow"]
+check_untyped_defs = true
+disallow_untyped_defs = true
+strict_optional = false
+no_implicit_optional = false
+ignore_missing_imports = true
+cache_dir = "tmp/mypy-cache"
+
+[tool.ruff.lint.per-file-ignores]
+"test/*.py" = ["E402"]

eraflow-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eraflow-0.1.0a1/src/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-0.1.0a1/src/eraflow/_version.py

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

eraflow-0.1.0a1/src/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