handshake-prompt 0.1.0__tar.gz

handshake_prompt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 handshake-prompt contributors
+
+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.

handshake_prompt-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: handshake-prompt
+Version: 0.1.0
+Summary: Handshake Prompt Protocol - grant AI Agents access to web services via a single copy-paste prompt
+Author: handshake-prompt contributors
+License: MIT
+Project-URL: Homepage, https://github.com/CGandGameEngineLearner/handshake-prompt
+Project-URL: Repository, https://github.com/CGandGameEngineLearner/handshake-prompt
+Project-URL: Issues, https://github.com/CGandGameEngineLearner/handshake-prompt/issues
+Keywords: ai,agent,protocol,websocket,handshake,llm,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-sock>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-flask>=1.3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# handshake-prompt (Python Server SDK)
+
+> Server-side SDK for the **Handshake Prompt Protocol (HPP)** — a lightweight
+> way to grant any AI Agent access to your web service via a single
+> copy-paste prompt. No API keys, no MCP servers, no env vars for end users.
+
+## Install
+
+```bash
+pip install handshake-prompt
+```
+
+## Quick start (Flask)
+
+```python
+from flask import Flask
+from flask_sock import Sock
+from handshake_prompt import HandshakeManager
+
+app  = Flask(__name__)
+sock = Sock(app)
+hm   = HandshakeManager(app, sock)   # done! HPP endpoints are now mounted.
+
+if __name__ == '__main__':
+    app.run(port=5000)
+```
+
+That's it. Your service now exposes:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/handshake/session`        | POST | Browser creates a handshake session |
+| `/handshake/context/<sid>`  | GET  | Agent reads current state (token-auth) |
+| `/handshake/action/<sid>`   | POST | Agent submits actions (token-auth) |
+| `/handshake/notify/<sid>`   | POST | Browser reports user edits |
+| `/handshake/diff/<sid>`     | GET  | Agent fetches incremental changes |
+| `/ws/handshake/<sid>`       | WS   | Real-time push channel (token-auth) |
+
+## Build a handshake prompt
+
+```python
+prompt_text = hm.build_prompt(session, base_url='https://your-service.com')
+# Display this text in the UI, let user copy-paste it to their Agent.
+```
+
+## Configure schema
+
+Schemas describe what fields the Agent should fill. Sent by the browser
+when creating a session:
+
+```json
+{
+  "mode": "form-fill",
+  "schema": [
+    {"key": "name",  "label": "Name",  "type": "string", "required": true, "example": "Alice"},
+    {"key": "age",   "label": "Age",   "type": "int",    "example": 30},
+    {"key": "vip",   "label": "VIP",   "type": "bool"}
+  ],
+  "context": {}    // current state, used by browser to pre-populate
+}
+```
+
+Supported types: `string` / `int` / `float` / `bool` / `datetime` /
+`array<string>` / `enum`. Custom validators can be plugged in via
+`HandshakeManager(validator=...)`.
+
+## Hooks
+
+Attach custom logic at key lifecycle points:
+
+```python
+@hm.on_create_session
+def bind_owner(sess, request):
+    """Bind a session to the current logged-in user"""
+    from flask import session as flask_session
+    sess.owner = flask_session.get('user_id')
+
+@hm.on_action
+def audit(sess, action, request):
+    """Audit every action; return False to veto"""
+    print(f'[AUDIT] sid={sess.sid} user={sess.owner} action={action}')
+
+@hm.on_done
+def notify_done(sess, applied, rejected, errors):
+    """Called after each batch of actions"""
+    pass
+```
+
+## Browser auth for `/notify`
+
+By default `/notify/<sid>` accepts any request (it's only used by
+browsers within the same origin). For stricter setups, supply a callable:
+
+```python
+def my_auth(request, sess):
+    return flask_session.get('user_id') == sess.owner
+
+hm = HandshakeManager(app, sock, require_browser_auth=my_auth)
+```
+
+## Security defaults
+
+- **Token entropy**: 192 bits (`secrets.token_urlsafe(24)`)
+- **Session ID entropy**: 128 bits (`secrets.token_hex(16)`)
+- **Timing-safe comparison**: `secrets.compare_digest`
+- **TTL**: 30 minutes default
+- **Rate limit**: 60 requests / minute / session
+- **User-data protection**: AI **cannot** overwrite fields marked
+  `by=user` or `by=user_edit`
+- **WebSocket auth**: connection-time token verification
+
+See `SPEC.md` of the main repository for full protocol details.
+
+## License
+
+MIT

handshake_prompt-0.1.0/README.md

@@ -0,0 +1,116 @@
+# handshake-prompt (Python Server SDK)
+
+> Server-side SDK for the **Handshake Prompt Protocol (HPP)** — a lightweight
+> way to grant any AI Agent access to your web service via a single
+> copy-paste prompt. No API keys, no MCP servers, no env vars for end users.
+
+## Install
+
+```bash
+pip install handshake-prompt
+```
+
+## Quick start (Flask)
+
+```python
+from flask import Flask
+from flask_sock import Sock
+from handshake_prompt import HandshakeManager
+
+app  = Flask(__name__)
+sock = Sock(app)
+hm   = HandshakeManager(app, sock)   # done! HPP endpoints are now mounted.
+
+if __name__ == '__main__':
+    app.run(port=5000)
+```
+
+That's it. Your service now exposes:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/handshake/session`        | POST | Browser creates a handshake session |
+| `/handshake/context/<sid>`  | GET  | Agent reads current state (token-auth) |
+| `/handshake/action/<sid>`   | POST | Agent submits actions (token-auth) |
+| `/handshake/notify/<sid>`   | POST | Browser reports user edits |
+| `/handshake/diff/<sid>`     | GET  | Agent fetches incremental changes |
+| `/ws/handshake/<sid>`       | WS   | Real-time push channel (token-auth) |
+
+## Build a handshake prompt
+
+```python
+prompt_text = hm.build_prompt(session, base_url='https://your-service.com')
+# Display this text in the UI, let user copy-paste it to their Agent.
+```
+
+## Configure schema
+
+Schemas describe what fields the Agent should fill. Sent by the browser
+when creating a session:
+
+```json
+{
+  "mode": "form-fill",
+  "schema": [
+    {"key": "name",  "label": "Name",  "type": "string", "required": true, "example": "Alice"},
+    {"key": "age",   "label": "Age",   "type": "int",    "example": 30},
+    {"key": "vip",   "label": "VIP",   "type": "bool"}
+  ],
+  "context": {}    // current state, used by browser to pre-populate
+}
+```
+
+Supported types: `string` / `int` / `float` / `bool` / `datetime` /
+`array<string>` / `enum`. Custom validators can be plugged in via
+`HandshakeManager(validator=...)`.
+
+## Hooks
+
+Attach custom logic at key lifecycle points:
+
+```python
+@hm.on_create_session
+def bind_owner(sess, request):
+    """Bind a session to the current logged-in user"""
+    from flask import session as flask_session
+    sess.owner = flask_session.get('user_id')
+
+@hm.on_action
+def audit(sess, action, request):
+    """Audit every action; return False to veto"""
+    print(f'[AUDIT] sid={sess.sid} user={sess.owner} action={action}')
+
+@hm.on_done
+def notify_done(sess, applied, rejected, errors):
+    """Called after each batch of actions"""
+    pass
+```
+
+## Browser auth for `/notify`
+
+By default `/notify/<sid>` accepts any request (it's only used by
+browsers within the same origin). For stricter setups, supply a callable:
+
+```python
+def my_auth(request, sess):
+    return flask_session.get('user_id') == sess.owner
+
+hm = HandshakeManager(app, sock, require_browser_auth=my_auth)
+```
+
+## Security defaults
+
+- **Token entropy**: 192 bits (`secrets.token_urlsafe(24)`)
+- **Session ID entropy**: 128 bits (`secrets.token_hex(16)`)
+- **Timing-safe comparison**: `secrets.compare_digest`
+- **TTL**: 30 minutes default
+- **Rate limit**: 60 requests / minute / session
+- **User-data protection**: AI **cannot** overwrite fields marked
+  `by=user` or `by=user_edit`
+- **WebSocket auth**: connection-time token verification
+
+See `SPEC.md` of the main repository for full protocol details.
+
+## License
+
+MIT

handshake_prompt-0.1.0/handshake_prompt/__init__.py

@@ -0,0 +1,27 @@
+# encoding=utf-8
+"""
+handshake-prompt
+================
+
+Server-side SDK for the Handshake Prompt Protocol (HPP).
+
+A lightweight protocol that lets users grant any AI Agent access to a web
+service via a single copy-paste of a "handshake prompt". No API keys, no MCP
+servers, no environment variables required for the end user.
+
+Quick start (Flask)::
+
+    from flask import Flask
+    from flask_sock import Sock
+    from handshake_prompt import HandshakeManager
+
+    app = Flask(__name__)
+    sock = Sock(app)
+    hm = HandshakeManager(app, sock)
+"""
+
+from .session import Session
+from .manager import HandshakeManager
+
+__version__ = "0.1.0"
+__all__ = ["HandshakeManager", "Session", "__version__"]

handshake_prompt-0.1.0/handshake_prompt/manager.py

@@ -0,0 +1,353 @@
+# encoding=utf-8
+"""
+HandshakeManager - 把 HPP 协议集成到 Flask 应用
+"""
+import json
+import secrets
+import time
+
+from .session import Session
+from .store import SessionStore
+
+
+# WebSocket 客户端的协议事件名称
+EVT_CONNECTED = 'connected'
+EVT_ACTION    = 'action'
+EVT_DONE      = 'done'
+EVT_ERROR     = 'error'
+
+
+class HandshakeManager:
+    """
+    将 HPP 注册到 Flask app + flask_sock 实例。
+
+    使用：
+
+        from flask import Flask
+        from flask_sock import Sock
+        from handshake_prompt import HandshakeManager
+
+        app = Flask(__name__)
+        sock = Sock(app)
+        hm = HandshakeManager(app, sock)
+
+        # 可选：通过钩子绑定业务身份
+        @hm.on_create_session
+        def bind_owner(sess, request):
+            sess.owner = session.get('user_id')   # Flask session
+
+    路由（默认 prefix='/handshake'）：
+        POST  /handshake/session         创建会话
+        GET   /handshake/context/<sid>   Agent 读取上下文（需 token）
+        POST  /handshake/action/<sid>    Agent 执行操作（需 token）
+        POST  /handshake/notify/<sid>    浏览器通知用户编辑（需 session 鉴权）
+        GET   /handshake/diff/<sid>      Agent 增量变更（需 token）
+        WS    /ws/handshake/<sid>        实时推送通道（需 token）
+    """
+
+    def __init__(self, app, sock, prefix='/handshake', ws_prefix='/ws/handshake',
+                 ttl=1800, rate_limit_per_min=60,
+                 store=None, validator=None,
+                 require_browser_auth=None):
+        self.app = app
+        self.sock = sock
+        self.prefix = prefix.rstrip('/')
+        self.ws_prefix = ws_prefix.rstrip('/')
+        self.ttl = ttl
+        self.rate_limit_per_min = rate_limit_per_min
+        self.store = store or SessionStore()
+        self.validator = validator
+        self.require_browser_auth = require_browser_auth   # callable(request) -> bool
+
+        # 钩子
+        self._on_create_callbacks = []
+        self._on_action_callbacks = []
+        self._on_done_callbacks = []
+
+        self._register(app, sock)
+        self.store.start_cleanup_thread()
+
+    # ── 钩子注册 ──────────────────────────────────────────
+
+    def on_create_session(self, fn):
+        """装饰器：会话创建时调用 fn(session, request)"""
+        self._on_create_callbacks.append(fn)
+        return fn
+
+    def on_action(self, fn):
+        """装饰器：Agent 提交 action 时调用 fn(session, action, request)"""
+        self._on_action_callbacks.append(fn)
+        return fn
+
+    def on_done(self, fn):
+        """装饰器：单次 action 批次完成后调用 fn(session, applied, rejected, errors)"""
+        self._on_done_callbacks.append(fn)
+        return fn
+
+    # ── 工具 ────────────────────────────────────────────
+
+    @staticmethod
+    def _check_token(sess, request):
+        token = request.headers.get('X-Handshake-Token') or request.args.get('token')
+        if not token:
+            return False
+        return secrets.compare_digest(token, sess.token)
+
+    @staticmethod
+    def _parse_ws_token(ws):
+        query = ws.environ.get('QUERY_STRING', '')
+        for part in query.split('&'):
+            if part.startswith('token='):
+                return part[6:]
+        return ''
+
+    def build_prompt(self, sess, base_url, instructions=None):
+        """
+        生成标准格式的握手提示词。
+        服务可调用此方法或自行实现，下方提供默认模板。
+        """
+        lines = [
+            f"# Handshake Prompt - {sess.mode}",
+            "",
+            "## Credentials",
+            f"- sessionId: {sess.sid}",
+            f"- token: {sess.token}",
+            f"- baseUrl: {base_url}",
+            f"- mode: {sess.mode}",
+            f"- expiresIn: {sess.expires_in()}s",
+            "",
+        ]
+        if instructions:
+            lines += ["## Instructions", instructions, ""]
+        lines += [
+            "## Usage",
+            "1. GET  {base}/handshake/context/{sid}   (header X-Handshake-Token: <token>)",
+            "2. POST {base}/handshake/action/{sid}    {\"actions\":[{\"type\":\"set\",\"key\":...,\"value\":...}]}",
+            "",
+            "## Security Notes",
+            "- This token is single-use and expires in 30 minutes",
+            "- Do NOT forward this prompt to others",
+            "- The server will reject any AI attempt to overwrite user-filled fields",
+            "",
+            "## Waiting for user's request...",
+        ]
+        return "\n".join(lines)
+
+    # ── 路由注册 ─────────────────────────────────────────
+
+    def _register(self, app, sock):
+        from flask import request, jsonify
+
+        prefix = self.prefix
+
+        def err(msg, code=400):
+            return jsonify({'error': msg}), code
+
+        # POST /session
+        @app.route(f'{prefix}/session', methods=['POST'])
+        def _hpp_session():
+            body = request.get_json(force=True, silent=True) or {}
+            mode    = body.get('mode', 'default')
+            schema  = body.get('schema', [])
+            context = body.get('context', {})
+            meta    = body.get('meta', {})
+
+            sid = secrets.token_hex(16)    # 128bit
+            sess = Session(
+                sid=sid, mode=mode, schema=schema, context=context,
+                ttl=self.ttl,
+                rate_limit_per_min=self.rate_limit_per_min,
+                meta=meta,
+                validator=self.validator,
+            )
+            # 钩子可写入 owner / 校验权限等
+            for cb in self._on_create_callbacks:
+                try:
+                    cb(sess, request)
+                except Exception as e:
+                    return err(str(e), 403)
+
+            self.store.put(sess)
+
+            return jsonify({
+                'sessionId':  sid,
+                'token':      sess.token,
+                'wsUrl':      f'{self.ws_prefix}/{sid}',
+                'contextUrl': f'{prefix}/context/{sid}',
+                'actionUrl':  f'{prefix}/action/{sid}',
+                'diffUrl':    f'{prefix}/diff/{sid}',
+                'notifyUrl':  f'{prefix}/notify/{sid}',
+                'expiresIn':  self.ttl,
+            })
+
+        # GET /context/<sid>
+        @app.route(f'{prefix}/context/<sid>', methods=['GET'])
+        def _hpp_context(sid):
+            sess = self.store.get(sid)
+            if not sess:
+                return err('session not found or expired', 404)
+            if not self._check_token(sess, request):
+                return err('invalid token', 403)
+            if not sess.check_rate_limit():
+                return err('rate limit exceeded', 429)
+            return jsonify(sess.to_dict())
+
+        # POST /action/<sid>
+        @app.route(f'{prefix}/action/<sid>', methods=['POST'])
+        def _hpp_action(sid):
+            sess = self.store.get(sid)
+            if not sess:
+                return err('session not found or expired', 404)
+            if not self._check_token(sess, request):
+                return err('invalid token', 403)
+            if not sess.check_rate_limit():
+                return err('rate limit exceeded', 429)
+
+            body     = request.get_json(force=True, silent=True) or {}
+            actions  = body.get('actions', [])
+            stream   = body.get('stream', True)
+            interval = max(0, body.get('intervalMs', 300)) / 1000.0
+
+            applied  = []
+            rejected = []
+            errors   = []
+
+            for act in actions:
+                if act.get('type') != 'set':
+                    errors.append({'action': act, 'msg': 'unsupported action type'})
+                    continue
+                key   = act.get('key')
+                value = act.get('value')
+                if key is None:
+                    errors.append({'action': act, 'msg': 'missing key'})
+                    continue
+
+                # 钩子：业务可以拒绝某个 action
+                veto = False
+                for cb in self._on_action_callbacks:
+                    try:
+                        result = cb(sess, act, request)
+                        if result is False:
+                            veto = True
+                            break
+                    except Exception as e:
+                        errors.append({'key': key, 'msg': str(e)})
+                        veto = True
+                        break
+                if veto:
+                    rejected.append(key)
+                    continue
+
+                # schema 类型校验
+                ok, msg = sess.validate_value(key, value)
+                if not ok:
+                    errors.append({'key': key, 'msg': msg})
+                    continue
+
+                # 写入（AI 不得覆盖用户字段）
+                ok = sess.set_value(key, value, 'ai')
+                if not ok:
+                    rejected.append(key)
+                    continue
+
+                applied.append(key)
+                if stream:
+                    sess.broadcast({'type': EVT_ACTION, 'key': key, 'value': value})
+                    if interval > 0:
+                        time.sleep(interval)
+
+            missing = sess.get_missing()
+            sess.broadcast({
+                'type':     EVT_DONE,
+                'applied':  len(applied),
+                'rejected': rejected,
+                'missing':  missing,
+            })
+
+            for cb in self._on_done_callbacks:
+                try:
+                    cb(sess, applied, rejected, errors)
+                except Exception:
+                    pass
+
+            return jsonify({
+                'ok':       True,
+                'applied':  applied,
+                'rejected': rejected,
+                'errors':   errors,
+                'missing':  missing,
+                'context':  sess.get_context(),
+            })
+
+        # POST /notify/<sid>
+        @app.route(f'{prefix}/notify/<sid>', methods=['POST'])
+        def _hpp_notify(sid):
+            sess = self.store.get(sid)
+            if not sess:
+                return err('session not found or expired', 404)
+            # 浏览器身份校验（可选 hook）
+            if self.require_browser_auth is not None:
+                if not self.require_browser_auth(request, sess):
+                    return err('browser auth failed', 403)
+            body  = request.get_json(force=True, silent=True) or {}
+            key   = body.get('key')
+            value = body.get('value')
+            if key is None:
+                return err('key is required')
+            sess.set_value(key, value, 'user')
+            return jsonify({'ok': True})
+
+        # GET /diff/<sid>
+        @app.route(f'{prefix}/diff/<sid>', methods=['GET'])
+        def _hpp_diff(sid):
+            sess = self.store.get(sid)
+            if not sess:
+                return err('session not found or expired', 404)
+            if not self._check_token(sess, request):
+                return err('invalid token', 403)
+            if not sess.check_rate_limit():
+                return err('rate limit exceeded', 429)
+            since = request.args.get('since', '')
+            changes = sess.get_diff_since(since) if since else sess.changes[-50:]
+            return jsonify({'sessionId': sid, 'since': since, 'changes': changes})
+
+        # WS /ws/handshake/<sid>
+        @sock.route(f'{self.ws_prefix}/<sid>')
+        def _hpp_ws(ws, sid):
+            sess = self.store.get(sid)
+            if not sess:
+                ws.send(json.dumps({'type': EVT_ERROR, 'msg': 'session not found'}))
+                ws.close()
+                return
+
+            token = self._parse_ws_token(ws)
+            if not token or not secrets.compare_digest(token, sess.token):
+                ws.send(json.dumps({'type': EVT_ERROR, 'msg': 'invalid token'}))
+                ws.close()
+                return
+
+            sess.ws_clients.add(ws)
+            ws.send(json.dumps({
+                'type':      EVT_CONNECTED,
+                'sessionId': sid,
+                'mode':      sess.mode,
+            }))
+
+            try:
+                while True:
+                    raw = ws.receive(timeout=60)
+                    if raw is None:
+                        break
+                    try:
+                        msg = json.loads(raw)
+                    except Exception:
+                        continue
+                    if msg.get('type') == 'userEdit':
+                        key   = msg.get('key')
+                        value = msg.get('value')
+                        if key is not None:
+                            sess.set_value(key, value, 'user')
+            except Exception:
+                pass
+            finally:
+                sess.ws_clients.discard(ws)

handshake_prompt-0.1.0/handshake_prompt/session.py

@@ -0,0 +1,190 @@
+# encoding=utf-8
+"""
+Session 对象 - 一个握手会话的完整状态
+"""
+import json
+import re
+import secrets
+import time
+from collections import deque
+from datetime import datetime, timezone
+
+
+def _now_iso():
+    return datetime.now(timezone.utc).astimezone().isoformat()
+
+
+def _validate_type(value, ftype):
+    """简易类型校验，可被 HandshakeManager(validator=...) 覆盖"""
+    if ftype in ('string', 'str'):
+        return isinstance(value, str)
+    if ftype in ('int', 'integer'):
+        return isinstance(value, int) and not isinstance(value, bool)
+    if ftype in ('float', 'number'):
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if ftype in ('bool', 'boolean'):
+        return isinstance(value, bool)
+    if ftype == 'datetime':
+        return isinstance(value, str) and bool(
+            re.match(r'\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}', value))
+    if ftype.startswith('array'):
+        return isinstance(value, list)
+    return True
+
+
+class Session:
+    """
+    单个握手会话。
+
+    存储：
+      - sid / token       会话标识 + 一次性访问令牌
+      - schema            字段定义 list[dict]
+      - values            当前值 {key: {value, by, at}}
+      - changes           变更历史 (最近 200)
+      - ws_clients        订阅的 WebSocket 集合
+
+    by 字段含义：
+      - 'empty'      未填
+      - 'user'       用户主动填写
+      - 'ai'         Agent 填写
+      - 'user_edit'  AI 填后被用户修改
+
+    安全：
+      - AI 不能覆盖 by=user 或 by=user_edit 的字段（在 set_value 中强制）
+    """
+
+    def __init__(self, sid, mode='default', schema=None, context=None,
+                 ttl=1800, rate_limit_per_min=60,
+                 owner=None, meta=None, validator=None):
+        self.sid           = sid
+        self.token         = secrets.token_urlsafe(24)     # 192 bit
+        self.mode          = mode
+        self.schema        = schema or []
+        self.owner         = owner       # 任意类型，用于绑定创建者身份
+        self.meta          = dict(meta or {})    # 任意业务元数据
+        self.ttl           = ttl
+        self.created_at    = time.time()
+        self.touched_at    = time.time()
+
+        self._rate_limit = rate_limit_per_min
+        self._rate_window = deque()
+        self._validator = validator or _validate_type
+
+        # 字段值
+        self.values = {}
+        for key, val in (context or {}).items():
+            by = 'user' if val not in (None, '', [], {}) else 'empty'
+            self.values[key] = {'value': val, 'by': by, 'at': _now_iso()}
+
+        # 变更历史
+        self.changes = []
+
+        # 订阅广播的 WebSocket
+        self.ws_clients = set()
+
+    # ── 生命周期 ─────────────────────────────────────────
+
+    def touch(self):
+        self.touched_at = time.time()
+
+    def is_expired(self):
+        return time.time() - self.touched_at > self.ttl
+
+    def expires_in(self):
+        return max(0, int(self.ttl - (time.time() - self.touched_at)))
+
+    # ── 频率限制 ─────────────────────────────────────────
+
+    def check_rate_limit(self):
+        now = time.time()
+        while self._rate_window and self._rate_window[0] < now - 60:
+            self._rate_window.popleft()
+        if len(self._rate_window) >= self._rate_limit:
+            return False
+        self._rate_window.append(now)
+        return True
+
+    # ── 数据 ────────────────────────────────────────────
+
+    def set_value(self, key, value, source):
+        """
+        设置字段。source ∈ {'ai', 'user'}
+
+        AI 试图覆盖 by=user / user_edit 时返回 False（不修改）。
+        用户修改 AI 填的字段时，by 自动升级为 user_edit。
+        """
+        current_by = self.values.get(key, {}).get('by', 'empty')
+
+        if source == 'ai' and current_by in ('user', 'user_edit'):
+            return False
+
+        if source == 'user' and current_by == 'ai':
+            source = 'user_edit'
+
+        old = self.values.get(key, {}).get('value')
+        now = _now_iso()
+        self.values[key] = {'value': value, 'by': source, 'at': now}
+        self.changes.append({
+            'key': key, 'from': old, 'to': value, 'by': source, 'at': now,
+        })
+        if len(self.changes) > 200:
+            self.changes.pop(0)
+        self.touch()
+        return True
+
+    def validate_value(self, key, value):
+        """根据 schema 校验单个字段值，返回 (ok, msg)"""
+        field_def = next((f for f in self.schema if f.get('key') == key), None)
+        if not field_def:
+            return True, None
+        ftype = field_def.get('type', 'string')
+        if not self._validator(value, ftype):
+            return False, f'type mismatch, expected {ftype}'
+        if ftype == 'enum':
+            options = [o.get('value') for o in field_def.get('options', [])]
+            if options and value not in options:
+                return False, f'value not in allowed options {options}'
+        return True, None
+
+    def get_context(self):
+        """完整上下文快照"""
+        return {k: v.copy() for k, v in self.values.items()}
+
+    def get_diff_since(self, since_iso):
+        return [c for c in self.changes if c['at'] > since_iso]
+
+    def get_missing(self):
+        """必填且未填的字段 key 列表"""
+        return [
+            f['key'] for f in self.schema
+            if f.get('required')
+            and self.values.get(f['key'], {}).get('value') in (None, '', [], {})
+        ]
+
+    # ── WebSocket 广播 ──────────────────────────────────
+
+    def broadcast(self, msg):
+        dead = set()
+        payload = json.dumps(msg, ensure_ascii=False)
+        for ws in list(self.ws_clients):
+            try:
+                ws.send(payload)
+            except Exception:
+                dead.add(ws)
+        self.ws_clients -= dead
+
+    # ── 序列化 ──────────────────────────────────────────
+
+    def to_dict(self, include_token=False):
+        out = {
+            'sessionId':  self.sid,
+            'mode':       self.mode,
+            'schema':     self.schema,
+            'context':    self.get_context(),
+            'missing':    self.get_missing(),
+            'meta':       self.meta,
+            'expiresIn':  self.expires_in(),
+        }
+        if include_token:
+            out['token'] = self.token
+        return out

handshake_prompt-0.1.0/handshake_prompt/store.py

@@ -0,0 +1,56 @@
+# encoding=utf-8
+"""
+Session 仓库 - 线程安全的会话存储与清理
+"""
+import threading
+import time
+
+from .session import Session
+
+
+class SessionStore:
+    """
+    内存型会话仓库。生产环境可继承并替换为 Redis 等持久化方案。
+    """
+
+    def __init__(self):
+        self._sessions = {}
+        self._lock = threading.Lock()
+
+    def put(self, sess: Session):
+        with self._lock:
+            self._sessions[sess.sid] = sess
+
+    def get(self, sid):
+        with self._lock:
+            sess = self._sessions.get(sid)
+        if sess and sess.is_expired():
+            with self._lock:
+                self._sessions.pop(sid, None)
+            return None
+        if sess:
+            sess.touch()
+        return sess
+
+    def remove(self, sid):
+        with self._lock:
+            self._sessions.pop(sid, None)
+
+    def cleanup_expired(self):
+        with self._lock:
+            expired = [k for k, v in self._sessions.items() if v.is_expired()]
+            for k in expired:
+                del self._sessions[k]
+        return len(expired)
+
+    def start_cleanup_thread(self, interval=300):
+        def _loop():
+            while True:
+                time.sleep(interval)
+                try:
+                    self.cleanup_expired()
+                except Exception:
+                    pass
+        t = threading.Thread(target=_loop, daemon=True)
+        t.start()
+        return t

handshake_prompt-0.1.0/handshake_prompt.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: handshake-prompt
+Version: 0.1.0
+Summary: Handshake Prompt Protocol - grant AI Agents access to web services via a single copy-paste prompt
+Author: handshake-prompt contributors
+License: MIT
+Project-URL: Homepage, https://github.com/CGandGameEngineLearner/handshake-prompt
+Project-URL: Repository, https://github.com/CGandGameEngineLearner/handshake-prompt
+Project-URL: Issues, https://github.com/CGandGameEngineLearner/handshake-prompt/issues
+Keywords: ai,agent,protocol,websocket,handshake,llm,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-sock>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-flask>=1.3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# handshake-prompt (Python Server SDK)
+
+> Server-side SDK for the **Handshake Prompt Protocol (HPP)** — a lightweight
+> way to grant any AI Agent access to your web service via a single
+> copy-paste prompt. No API keys, no MCP servers, no env vars for end users.
+
+## Install
+
+```bash
+pip install handshake-prompt
+```
+
+## Quick start (Flask)
+
+```python
+from flask import Flask
+from flask_sock import Sock
+from handshake_prompt import HandshakeManager
+
+app  = Flask(__name__)
+sock = Sock(app)
+hm   = HandshakeManager(app, sock)   # done! HPP endpoints are now mounted.
+
+if __name__ == '__main__':
+    app.run(port=5000)
+```
+
+That's it. Your service now exposes:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/handshake/session`        | POST | Browser creates a handshake session |
+| `/handshake/context/<sid>`  | GET  | Agent reads current state (token-auth) |
+| `/handshake/action/<sid>`   | POST | Agent submits actions (token-auth) |
+| `/handshake/notify/<sid>`   | POST | Browser reports user edits |
+| `/handshake/diff/<sid>`     | GET  | Agent fetches incremental changes |
+| `/ws/handshake/<sid>`       | WS   | Real-time push channel (token-auth) |
+
+## Build a handshake prompt
+
+```python
+prompt_text = hm.build_prompt(session, base_url='https://your-service.com')
+# Display this text in the UI, let user copy-paste it to their Agent.
+```
+
+## Configure schema
+
+Schemas describe what fields the Agent should fill. Sent by the browser
+when creating a session:
+
+```json
+{
+  "mode": "form-fill",
+  "schema": [
+    {"key": "name",  "label": "Name",  "type": "string", "required": true, "example": "Alice"},
+    {"key": "age",   "label": "Age",   "type": "int",    "example": 30},
+    {"key": "vip",   "label": "VIP",   "type": "bool"}
+  ],
+  "context": {}    // current state, used by browser to pre-populate
+}
+```
+
+Supported types: `string` / `int` / `float` / `bool` / `datetime` /
+`array<string>` / `enum`. Custom validators can be plugged in via
+`HandshakeManager(validator=...)`.
+
+## Hooks
+
+Attach custom logic at key lifecycle points:
+
+```python
+@hm.on_create_session
+def bind_owner(sess, request):
+    """Bind a session to the current logged-in user"""
+    from flask import session as flask_session
+    sess.owner = flask_session.get('user_id')
+
+@hm.on_action
+def audit(sess, action, request):
+    """Audit every action; return False to veto"""
+    print(f'[AUDIT] sid={sess.sid} user={sess.owner} action={action}')
+
+@hm.on_done
+def notify_done(sess, applied, rejected, errors):
+    """Called after each batch of actions"""
+    pass
+```
+
+## Browser auth for `/notify`
+
+By default `/notify/<sid>` accepts any request (it's only used by
+browsers within the same origin). For stricter setups, supply a callable:
+
+```python
+def my_auth(request, sess):
+    return flask_session.get('user_id') == sess.owner
+
+hm = HandshakeManager(app, sock, require_browser_auth=my_auth)
+```
+
+## Security defaults
+
+- **Token entropy**: 192 bits (`secrets.token_urlsafe(24)`)
+- **Session ID entropy**: 128 bits (`secrets.token_hex(16)`)
+- **Timing-safe comparison**: `secrets.compare_digest`
+- **TTL**: 30 minutes default
+- **Rate limit**: 60 requests / minute / session
+- **User-data protection**: AI **cannot** overwrite fields marked
+  `by=user` or `by=user_edit`
+- **WebSocket auth**: connection-time token verification
+
+See `SPEC.md` of the main repository for full protocol details.
+
+## License
+
+MIT

handshake_prompt-0.1.0/handshake_prompt.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+handshake_prompt/__init__.py
+handshake_prompt/manager.py
+handshake_prompt/session.py
+handshake_prompt/store.py
+handshake_prompt.egg-info/PKG-INFO
+handshake_prompt.egg-info/SOURCES.txt
+handshake_prompt.egg-info/dependency_links.txt
+handshake_prompt.egg-info/requires.txt
+handshake_prompt.egg-info/top_level.txt

handshake_prompt-0.1.0/handshake_prompt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

handshake_prompt-0.1.0/handshake_prompt.egg-info/requires.txt

@@ -0,0 +1,8 @@
+flask>=2.0
+flask-sock>=0.7.0
+
+[dev]
+pytest>=7.0
+pytest-flask>=1.3
+build
+twine

handshake_prompt-0.1.0/handshake_prompt.egg-info/top_level.txt

@@ -0,0 +1 @@
+handshake_prompt

handshake_prompt-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name            = "handshake-prompt"
+version         = "0.1.0"
+description     = "Handshake Prompt Protocol - grant AI Agents access to web services via a single copy-paste prompt"
+readme          = "README.md"
+requires-python = ">=3.8"
+license         = { text = "MIT" }
+keywords        = ["ai", "agent", "protocol", "websocket", "handshake", "llm", "automation"]
+authors         = [{ name = "handshake-prompt contributors" }]
+classifiers     = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "flask>=2.0",
+    "flask-sock>=0.7.0",
+]
+
+[project.urls]
+Homepage   = "https://github.com/CGandGameEngineLearner/handshake-prompt"
+Repository = "https://github.com/CGandGameEngineLearner/handshake-prompt"
+Issues     = "https://github.com/CGandGameEngineLearner/handshake-prompt/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-flask>=1.3",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["handshake_prompt*"]

handshake_prompt-0.1.0/setup.cfg

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