零信任架构实战：基于海宇活体识别V步骤1构建自动化远程公证会话初始化网关

破解远程公证意愿核验痛点：从线下柜台面签录像到云端活体会话穿透直连

在远程在线公证、房产委托代办以及电子遗嘱存证平台的司法合规实践中，确认申请人系"本人真实在场且处于实时自然交互状态"是证据链具备法律效力的核心前提。传统的线上公证辅助核验往往要求当事人自行录制手持证件朗读声明的视频并上传后台，再由公证员逐帧人工审阅画面连贯性与口型匹配度。这种作业方式不仅耗费大量司法辅助人力、跨地域签署等待周期漫长，而且异步上传的静态视频文件缺乏实时环境光交互与防重放令牌约束，难以在采集源头排除非实时画面注入等合规隐患，给后续公证文书出具与司法存证带来显著的履约风险。

在获得公证申请人或立遗嘱人明确知情授权的前提下，平台架构师可将活体识别V步骤1接口作为远程生物核验链路的会话编排中枢。业务后端仅需在加密请求体中传入本系统的前端回调地址（return_url），即可通过加密网关实时申请具备防重放特性的单次核验会话。接口响应经由服务端本地 AES-128-CBC 解密后，将返回有效期为 2 小时的唯一会话凭证（token）以及标准化的前端活体采集入口地址（url）。在此基础上，服务端可根据公证事项的风险等级与申请人年龄特征，在引导前端跳转至 url 时动态挂载细粒度的采集控制参数------例如针对高价值遗产存证开启随机闪光防摄像头劫持检测（antiCameraHack）与云端大模型活体算法（backLiveOn），針對高龄立遗嘱人定制低负担的局部动作样式（style），并显式关闭浏览器端回调携带凭证（returnUrlIncludeToken=false），从而在保障司法级核验严谨性的同时大幅提升适老化交互体验。

将活体识别V步骤1的会话初始化与 URL 策略组装逻辑封装为高内聚的 Python 微服务组件，能够帮助电子公证平台实现核验凭证的闭环托管与前置准入校验，确保每一份在线签署的公证文书都建立在真实、可溯的实时生物核验会话之上。

Python 加密通信集成：构建高可用审核管道

1. 核心参数与加密配置

接口地址 : https://api.haiyudata.com/api/v1/IVYZX5QJ (需在 URL 附加 ?t=13位时间戳)
请求方式 : POST
请求头 :
- Access-Id: 账号的 Access-Id (必填)
- Content-Type: application/json
关键入参 :
- return_url: 请求回调地址，前端完成活体人脸采集后将回跳至此地址；应用在获取响应中的采集 url 后，还可按需附加 style、actionLiveParam、antiCameraHack、returnUrlIncludeToken 等采集控制参数引导前端跳转（必填）
鉴权与加密机制 : 使用账户的 16 进制 Access Key 作为密钥，采用 AES-128 算法的 CBC 模式。每次请求需动态生成 16 字节的 IV（初始化向量），并配合 PKCS7 填充，最终将 IV 与密文拼接后进行 Base64 编码放入请求体 data 字段中。

2. 标准化调用代码 (Python)

以下 Python 代码围绕"远程在线公证与电子遗嘱存证平台活体核验会话初始化服务"场景构建，完整实现了 return_url 加密上送、token 与采集 url 解密提取，以及面向不同公证业务等级的 H5 采集跳转链接安全组装逻辑。运行前请安装依赖库：pip install pycryptodome requests。

python 复制代码

import os
import time
import json
import base64
import logging
from urllib.parse import urlencode, urlparse, urlunparse, parse_qsl
from typing import Dict, Any, Optional
import requests
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad

# 初始化公证活体网关日志配置
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s - %(message)s"
)
logger = logging.getLogger("NotaryLivenessSessionService")


class NotaryLivenessStep1Orchestrator:
    """
    远程在线公证与电子遗嘱存证平台：活体核验步骤1会话初始化与防重放编排器
    负责获取 2 小时有效期的核验 token，并组装定制化前端采集跳转 URL
    """

    def __init__(self, access_id: str, access_key_hex: str, timeout: int = 8):
        """
        初始化加密通信客户端
        :param access_id: 海宇平台分配的 Access-Id
        :param access_key_hex: 32位16进制字符串格式的 Access Key (16字节密钥)
        :param timeout: 请求超时时间（秒）
        """
        self.endpoint = "https://api.haiyudata.com/api/v1/IVYZX5QJ"
        self.access_id = access_id.strip()
        self.key_bytes = bytes.fromhex(access_key_hex.strip())
        if len(self.key_bytes) != 16:
            raise ValueError("Access Key 必须为代表 16 字节的 32 位 16 进制字符串")
        self.timeout = timeout

    def _encrypt_payload(self, plain_dict: Dict[str, Any]) -> str:
        """
        使用 AES-128-CBC + PKCS7 填充加密 JSON 入参，返回 Base64(IV + Ciphertext)
        """
        plain_bytes = json.dumps(plain_dict, ensure_ascii=False).encode("utf-8")
        iv = os.urandom(16)
        cipher = AES.new(self.key_bytes, AES.MODE_CBC, iv)
        padded_bytes = pad(plain_bytes, AES.block_size, style="pkcs7")
        encrypted_bytes = cipher.encrypt(padded_bytes)
        return base64.b64encode(iv + encrypted_bytes).decode("utf-8")

    def _decrypt_payload(self, encrypted_b64: str) -> Dict[str, Any]:
        """
        提取 Base64 解码后的前 16 字节作为 IV，解密还原内层业务 JSON
        """
        raw_bytes = base64.b64decode(encrypted_b64)
        if len(raw_bytes) <= 16:
            raise ValueError("加密响应负载长度异常，无法提取 16 字节初始化向量 IV")
        iv = raw_bytes[:16]
        ciphertext = raw_bytes[16:]
        cipher = AES.new(self.key_bytes, AES.MODE_CBC, iv)
        decrypted_padded = cipher.decrypt(ciphertext)
        plain_bytes = unpad(decrypted_padded, AES.block_size, style="pkcs7")
        return json.loads(plain_bytes.decode("utf-8"))

    @staticmethod
    def _mask_token(token: str) -> str:
        """对核验凭证 token 进行日志脱敏处理，防止敏感会话凭据明文泄露"""
        if not token or len(token) <= 8:
            return "****"
        return f"{token[:4]}****{token[-4:]}"

    @staticmethod
    def _build_collection_redirect_url(
        base_collection_url: str,
        notary_scene: str = "ELDERLY_WILL_PRESERVATION",
        custom_title: str = "公证签署活体意愿核验"
    ) -> str:
        """
        根据远程公证细分场景，向步骤1返回的采集 url 注入细粒度前端采集控制参数
        """
        # 基础安全与体验参数配置：强制关闭浏览器回调 URL 携带 token，防止前端暴露凭据
        collect_params: Dict[str, Any] = {
            "title": custom_title[:32],
            "returnUrlIncludeToken": "false",
            "foreLiveOn": "true",
            "showSuccess": "false",
            "showFail": "true",
            "hideGuidePage": "false",
            "enableH5CompatibleModel": "true"
        }

        if notary_scene == "ELDERLY_WILL_PRESERVATION":
            # 适老化电子遗嘱存证场景：采用样式2（仅从眨眼、张嘴中随机选1个局部动作），降低高龄老人大幅度转头负担
            # 同时开启云端大模型复核与闪光检测，保障高法律效力
            collect_params.update({
                "style": "2",
                "actionMutex": "false",
                "antiCameraHack": "true",
                "backLiveOn": "true"
            })
        elif notary_scene == "HIGH_VALUE_PROPERTY_ENTRUST":
            # 大额房产委托公证场景：采用样式1（头部动作+局部动作随机组合）+ 动作互斥 + 闪光防劫持 + 云端大模型
            collect_params.update({
                "style": "1",
                "actionMutex": "true",
                "antiCameraHack": "true",
                "backLiveOn": "true"
            })
        else:
            # 常规在线公证声明场景：标准动作组合
            collect_params.update({
                "style": "1",
                "actionMutex": "false",
                "antiCameraHack": "false",
                "backLiveOn": "false"
            })

        parsed = urlparse(base_collection_url)
        existing_query = dict(parse_qsl(parsed.query))
        existing_query.update(collect_params)
        merged_query_str = urlencode(existing_query)
        return urlunparse(parsed._replace(query=merged_query_str))

    def init_liveness_session(
        self,
        notary_case_id: str,
        return_url: str,
        notary_scene: str = "ELDERLY_WILL_PRESERVATION"
    ) -> Dict[str, Any]:
        """
        发起活体识别V步骤1请求，初始化公证活体会话并生成前端跳转地址
        :param notary_case_id: 公证处内部案卷号/存证单号（用于绑定服务端缓存）
        :param return_url: 采集完成后的前端回跳地址
        :param notary_scene: 公证业务场景标识
        """
        request_payload = {
            "return_url": return_url.strip()
        }

        encrypted_data = self._encrypt_payload(request_payload)
        timestamp_ms = int(time.time() * 1000)
        request_url = f"{self.endpoint}?t={timestamp_ms}"

        headers = {
            "Access-Id": self.access_id,
            "Content-Type": "application/json"
        }

        logger.info(f"开始初始化公证活体核验会话 | 案卷号: {notary_case_id} | 场景: {notary_scene}")

        try:
            response = requests.post(
                url=request_url,
                headers=headers,
                json={"data": encrypted_data},
                timeout=self.timeout
            )
            response.raise_for_status()
            resp_json = response.json()

            code = resp_json.get("code")
            transaction_id = resp_json.get("transaction_id", "N/A")
            message = resp_json.get("message", "")

            if not resp_json.get("data"):
                logger.warning(
                    f"活体会话初始化未返回加密数据 | 案卷号: {notary_case_id} | "
                    f"流水号: {transaction_id} | code: {code} | message: {message}"
                )
                return {
                    "success": False,
                    "code": code,
                    "message": message,
                    "transaction_id": transaction_id,
                    "notary_case_id": notary_case_id
                }

            decrypted_data = self._decrypt_payload(resp_json["data"])
            session_token = decrypted_data.get("token", "")
            raw_collection_url = decrypted_data.get("url", "")

            # 构建带有防摄像头劫持、适老化动作样式及隐藏 URL Token 的完整前端采集地址
            full_redirect_url = self._build_collection_redirect_url(
                base_collection_url=raw_collection_url,
                notary_scene=notary_scene
            )

            logger.info(
                f"公证活体会话初始化成功 | 案卷号: {notary_case_id} | 流水号: {transaction_id} | "
                f"Token(脱敏): {self._mask_token(session_token)} | 有效期: 7200秒"
            )

            # 注意：session_token 应保存在服务端 Redis 中并与 notary_case_id 绑定，不直接暴露给不可信终端
            return {
                "success": True,
                "code": code,
                "message": message,
                "transaction_id": transaction_id,
                "notary_case_id": notary_case_id,
                "server_side_token": session_token,
                "token_ttl_seconds": 7200,
                "raw_collection_url": raw_collection_url,
                "frontend_redirect_url": full_redirect_url
            }

        except requests.exceptions.RequestException as req_err:
            logger.error(f"活体识别V步骤1网络请求异常 | 案卷号: {notary_case_id} | 错误: {req_err}")
            raise
        except Exception as dec_err:
            logger.error(f"活体识别V步骤1报文加解密异常 | 案卷号: {notary_case_id} | 错误: {dec_err}")
            raise


if __name__ == "__main__":
    # 从环境变量加载鉴权凭证
    ACCESS_ID = os.getenv("HAIYU_ACCESS_ID", "your_haiyu_access_id")
    ACCESS_KEY_HEX = os.getenv("HAIYU_ACCESS_KEY_HEX", "abcdef0123456789abcdef0123456789")

    orchestrator = NotaryLivenessStep1Orchestrator(
        access_id=ACCESS_ID,
        access_key_hex=ACCESS_KEY_HEX
    )

    # 示例：为电子遗嘱存证案卷初始化活体采集会话
    session_info = orchestrator.init_liveness_session(
        notary_case_id="WILL-20261003-0089",
        return_url="https://notary.example.com/h5/will-signing/callback?case_id=WILL-20261003-0089",
        notary_scene="ELDERLY_WILL_PRESERVATION"
    )
    print(json.dumps(session_info, ensure_ascii=False, indent=2))

3. 终端快捷验证 (cURL)

在接入调试期间，开发者可先将包含 return_url 的明文 JSON 按 AES-128-CBC 规则加密并拼接 16 字节随机 IV 编码为 Base64 字符串，再通过以下 cURL 命令验证接口响应：

bash 复制代码

curl -X POST "https://api.haiyudata.com/api/v1/IVYZX5QJ?t=1727521900000" \
  -H "Access-Id: YOUR_ACCESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6dPoiuytrewqAsdfghjklZxcvbnm0123456789abcdef=="
  }'

核心活体会话数据解析与业务映射

活体识别V步骤1不仅承担着服务端加密握手与防重放凭证（token）签发的职责，还通过前端采集跳转地址（url）支持丰富的客户端交互与算法调度参数。在远程公证与电子遗嘱存证场景中，合理配置这些参数是平衡安全性与签署完成率的关键。

关键字段解析表

字段分类	字段名	类型	必填/返回	详细技术说明与远程公证业务映射
加密请求入参	`return_url`	`string`	必填	前端完成活体人脸采集后回跳的业务方接收地址，建议携带公证案卷流水号以便前端恢复签署上下文。
解密核心返回	`token`	`string`	必返	活体采集与结果查询唯一凭证：有效期严格限制为 2 小时（7200秒）。有效期内可发起采集请求与后续结果查询，且重复采集触发的结果将被自动忽略，具备天然的防重放特性。
解密核心返回	`url`	`string`	必返	前端活体采集基础地址：服务端解密获取后，可拼接下述采集控制参数引导前端 H5 或小程序 WebView 跳转。
采集跳转参数	`actionLiveParam`	`varchar`	选填	自定义动作序列数组，以英文逗号分隔（如 `LookLeft,OpenMouth`），默认无需传递，交由 `style` 策略随机编排。
采集跳转参数	`style`	`varchar`	选填	动作样式选择： `"1"`：从摇头、点头、左转头、右转头 4 个头部动作中随机选 1 个，再从眨眼、张嘴 2 个局部动作中随机选 1 个并随机组合顺序（适合常规中青年公证申请人）； `"2"`：仅从眨眼、张嘴 2 个局部动作中随机选 1 个（适合高龄立遗嘱人或行动不便申请人）。
采集跳转参数	`actionMutex`	`Boolean`	选填	是否检查动作互斥（默认 `false`）。设为 `false` 时动作不匹配不会立即判定失败，有助于提升老年群体一次采集通过率。
采集跳转参数	`antiCameraHack`	`Boolean`	选填	闪光防摄像头劫持检测（默认 `false`）。开启后将通过随机性屏幕闪光校验视频是否为真实物理环境实时采集，对高价值遗产公证及房产委托强烈建议设为 `true`。
采集跳转参数	`foreLiveOn` / `backLiveOn`	`Boolean`	选填	端云协同活体算法开关：`foreLiveOn`（默认 `true`）启用客户端轻量级小模型实时预检；`backLiveOn`（默认 `false`）启用服务器端云端大模型深度核验，在严肃司法存证场景建议同时开启。
采集跳转参数	`showSuccess` / `showFail`	`Boolean`	选填	结果页展示控制：`showSuccess` 默认 `false`（采集成功后直接静默跳回公证签署页），`showFail` 默认 `true`（展示具体失败原因如光线过暗，便于当事人即时调整）。
采集跳转参数	`hideGuidePage`	`Boolean`	选填	是否隐藏采集前引导页（默认 `false` 不隐藏）。对于首次使用远程公证系统的当事人，建议保留引导页以降低操作失误。
采集跳转参数	`title`	`varchar`	选填	采集页面顶部标题文本，最长 32 个字符（默认 `"活体人脸采集"`），可定制为 `"电子遗嘱意愿活体核验"`。
采集跳转参数	`enableH5CompatibleModel`	`Boolean`	选填	H5 降级兼容模式（默认 `true`）。当终端浏览器不支持端侧算法预检时，设为 `true` 将自动切换为原生相机录制视频方式完成核验，避免用户中断流程。
采集跳转参数	`returnUrlIncludeToken`	`Boolean`	选填	回调 URL 是否附带 Token （因历史兼容默认 `true`）。由于 `token` 暴露在浏览器地址栏存在泄漏风险，生产环境强烈建议显式设置为 `false`。

技术提示：

防凭证泄露与幂等性机制 ：token 有效期为 2 小时，且在同一 token 下重复发起的采集结果会被底层自动忽略。工程实现时，务必将 returnUrlIncludeToken 显式设为 false，由后端通过公证案卷 Session 维护 token 映射关系，防止凭证在浏览器历史记录或 Referer 头中暴露。

PII 与会话日志脱敏规范 ：在记录公证申请人核验日志时，涉及关联的个人身份标识与联系方式须严格执行掩码脱敏（如关联手机号记录为 138****0000、身份证号脱敏为 310101********1234、核验凭证 token 仅打印首尾各 4 位），确保日志审计系统符合司法数据隐私规范。

场景化应用：让核验数据赋能合规闭环

通过灵活组合活体识别V步骤1返回的会话凭证与采集端策略参数，远程公证与电子存证平台能够针对不同司法业务场景构建差异化的核验闭环：

1. 高龄立遗嘱人"适老化"电子遗嘱在线存证

在立遗嘱人通过微信小程序或 H5 办理电子遗嘱存证时，许多高龄长者面对复杂的"快速左右转头+点头"组合动作容易出现眩晕或动作超时失败。平台后端在调用活体识别V步骤1获取 url 后，可根据实名认证年龄（如年满 65 周岁）自动组装 style=2、actionMutex=false 与 hideGuidePage=false 参数，仅要求老人完成简单的"眨眼"或"张嘴"单一局部动作；同时在后台静默开启 antiCameraHack=true（屏幕随机闪光活体反射检测）与 backLiveOn=true（云端大模型深度检测）。这样既大幅降低了老年群体的操作门槛，又通过光学反射与云端大模型双重校验保障了立遗嘱过程的真实实时性。

2. 跨国/异地大额不动产委托公证防重放核查

针对身处海外或异地的产权人办理房产出售委托公证，业务风险等级极高。公证系统在当事人进入视频面签室前，先触发步骤1接口生成专属 token（有效期 2 小时），并将其与当前公证申请单号在服务端 Redis 中建立一对一强绑定，同时设置 style=1、actionMutex=true、antiCameraHack=true 及 returnUrlIncludeToken=false。由于底层机制保证同一 token 下重复触发的采集结果会被忽略，即便网络异常产生多次回调，系统也能确保单次公证签署仅采信首次有效完成的实时活体采集证据，若多次采集未通过（showFail=true 提示环境光线或动作不匹配），系统将自动触发人工复核提醒并转接公证员一对一视频核实。

3. 碎片化移动终端下的 H5 签署高可用容灾兜底

公证当事人在移动端打开电子签署链接时，往往处于微信内置 WebView、各类手机自带浏览器等高度碎片化的运行环境中，部分老旧机型可能无法加载 WebAssembly 前端活体小模型。通过在步骤1返回的采集地址中保持 enableH5CompatibleModel=true 与 foreLiveOn=true，当客户端环境支持算法预检时优先执行高速端侧活体引导；一旦检测到老旧浏览器不支持实时预检，系统无需中断公证流程或要求用户复制链接切换浏览器，而是平滑降级为调用手机原生相机录制短视频并交由云端核验，显著提升远程公证全链路的签署转化率。

生产环境接入的安全与合规边界

隐私授权与司法存证告知 ：生物识别信息（人脸活体视频及特征值）属于高度敏感的个人信息。在调用活体识别V步骤1初始化会话前，平台必须向申请人展示独立的《远程公证生物识别信息采集授权书》，明确告知采集目的仅限当前公证案卷核验与司法存证使用，并将授权记录与返回的 transaction_id 关联归档。
密文传输与服务端 Token 托管 ：接口通信全程依赖 AES-128-CBC 对称加密，每次请求必须动态生成 16 字节随机 IV 并与密文拼接后执行 Base64 编码。解密获得的 token 属于核心核验凭据，严禁通过 URL Query 参数回传至前端浏览器（务必配置 returnUrlIncludeToken=false），应加密存储于服务端分布式缓存中并设置与接口一致的 2 小时（7200秒）过期自动销毁策略。
限流控制与会话防刷保护 ：为防范恶意脚本频繁请求步骤1接口耗尽账户配额，建议在公证业务网关层针对单一实名申请人 ID 或公证案卷号设置会话复用与频次控制逻辑------若当前案卷已存在未过期的有效 token 且尚未完成采集，在合理时间窗口内可直接复用已签发的采集 url，避免短时间内重复初始化新会话。