ChatComment 0.1.1__tar.gz → 0.2.1__tar.gz

chatcomment-0.2.1/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.1
+
+- `--require-existing-db` 在 Store 初始化之前验证既有 SQLite 完整性、必要表/字段和可读性，拒绝空文件、损坏或错误 schema。
+- 只读源文件并在私有稳定快照上校验，保留活跃 WAL 支持，不在挂载目录创建 SQLite 辅助文件；允许完整 schema 的零留言数据库。
+
+## 0.2.0
+
+- 平台中立的 `AccessContext` / `SiteAccess` API，复用 ChatLogin 主体并显式检查每站 read/comment/manage/owner；管理 grant 按 session 和站点区分。
+- 独立服务签名网关模式，验证短时 method/path/query/body 绑定上下文；所有非 health 路由要求签名，不接受旧全局 token 作为替代。
+- 邮箱齿轮提示、管理列表、再认证和前端 CSRF 端点按站点及平台配置；不向前端暴露期望邮箱或服务器密钥。
+- 迁移所需的 `site allow-origin` 只更新允许来源，保留字段设置和全部留言；`--require-existing-db` 防止缺少持久卷时创建空库。
+
+## 0.1.1
+
+- 留言区仅显示一个齿轮入口；本人填写管理员邮箱后由服务器确认显示，不按昵称判断、不下发管理员邮箱。
+- 提供邮箱/密码验证页，网关可在现有账号校验后授予短时管理权限；管理 API 仍由服务器角色授权。
+
+## 0.1.0
+
+- Python/SQLite 留言服务、无依赖 JS 组件及同源管理界面。
+- 站点来源和页面白名单，匿名与字段设置，服务器端校验、审核、软删除、JSON 导出与 SQLite 在线备份。
+- 私有站点可信网关模式；管理 token 留在服务器。
+- 独立留言板与嵌入组件共用数据；服务端 owner / reader 权限与设置入口显示。

{chatcomment-0.1.1 → chatcomment-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ChatComment
-Version: 0.1.1
+Version: 0.2.1
 Summary: Embeddable comments with a Python server, SQLite storage and a small JavaScript widget.
 Author: ChatArch
 License-Expression: MIT
@@ -15,6 +15,7 @@ Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Requires-Dist: chatlogin<0.3.0,>=0.2.1; extra == "dev"
 Dynamic: license-file
 
 # ChatComment
@@ -43,6 +44,8 @@ chatcomment serve --token-file ~/.chatarch/chatcomment/admin-token
 
 API、网关接入、备份与恢复见 [docs/api.md](docs/api.md)、[docs/deployment.md](docs/deployment.md)。本包不自动开放防火墙或注册 DNS，也不包含云服务凭据。
 
+多用户平台接入使用 [平台服务协议](docs/platform.md)：`--gateway-key-env` 启用按主体/session/站点校验的签名上下文，所有非 health 路由均拒绝未签名访问，兼容独立 Coolify 资源。`AccessContext.from_chatlogin()` 复用已验证的 ChatLogin Session；项目 ACL 与密码二次验证由平台拥有，账户全局 admin 不能自动获得站点权限。旧 `--token-file` 模式仅保留给已有单网关部署迁移使用。
+
 独立留言板为 `/board?site=personal-blog&page=%2Fpost%2Fone`，与嵌入表单读写同一留言流。组件只提供一个齿轮入口：已登录 owner 在邮箱栏填写匹配邮箱后，服务器返回显示提示；昵称不参与判断，邮箱不下发到 JS 配置。齿轮指向邮箱/密码验证页；网关须实现 `/api/admin/reauth` 并在校验现有账号后授予短时管理权限。公开站点没有该提示。
 
 网关为普通成员设置 `X-ChatComment-Role: reader`，仅经服务端验证的 owner 使用 `admin`；管理接口另行验证权限。公开浏览器不能靠昵称、邮箱或伪造角色 header 获得权限，因为缺少服务器 Bearer token。服务器可为受信 owner 请求附加 `X-ChatComment-Admin-Email`，只用于入口提示。完整验证合约见部署文档。

{chatcomment-0.1.1 → chatcomment-0.2.1}/README.md

@@ -24,6 +24,8 @@ chatcomment serve --token-file ~/.chatarch/chatcomment/admin-token
 
 API、网关接入、备份与恢复见 [docs/api.md](docs/api.md)、[docs/deployment.md](docs/deployment.md)。本包不自动开放防火墙或注册 DNS，也不包含云服务凭据。
 
+多用户平台接入使用 [平台服务协议](docs/platform.md)：`--gateway-key-env` 启用按主体/session/站点校验的签名上下文，所有非 health 路由均拒绝未签名访问，兼容独立 Coolify 资源。`AccessContext.from_chatlogin()` 复用已验证的 ChatLogin Session；项目 ACL 与密码二次验证由平台拥有，账户全局 admin 不能自动获得站点权限。旧 `--token-file` 模式仅保留给已有单网关部署迁移使用。
+
 独立留言板为 `/board?site=personal-blog&page=%2Fpost%2Fone`，与嵌入表单读写同一留言流。组件只提供一个齿轮入口：已登录 owner 在邮箱栏填写匹配邮箱后，服务器返回显示提示；昵称不参与判断，邮箱不下发到 JS 配置。齿轮指向邮箱/密码验证页；网关须实现 `/api/admin/reauth` 并在校验现有账号后授予短时管理权限。公开站点没有该提示。
 
 网关为普通成员设置 `X-ChatComment-Role: reader`，仅经服务端验证的 owner 使用 `admin`；管理接口另行验证权限。公开浏览器不能靠昵称、邮箱或伪造角色 header 获得权限，因为缺少服务器 Bearer token。服务器可为受信 owner 请求附加 `X-ChatComment-Admin-Email`，只用于入口提示。完整验证合约见部署文档。

{chatcomment-0.1.1 → chatcomment-0.2.1}/docs/api.md

@@ -1,9 +1,11 @@
 # Commands and APIs
 
-`chatcomment --help`, `--version`, `--tree`, `--tree-brief` describe the installed CLI. Commands: `serve`, `site register`, `site list`, `backup`. Python API: `Store.register`, `site`, `sites`, `configure`, `create`, `comments`, `moderate`, `backup`; `server.make_handler` and `server.serve` expose the same HTTP service.
+`chatcomment --help`, `--version`, `--tree`, `--tree-brief` describe the installed CLI. Commands: `serve`, `site register`, `site list`, `site allow-origin`, `backup`. Python API: `Store.register`, `site`, `sites`, `configure`, `allow_origin`, `create`, `comments`, `moderate`, `backup`; `server.make_handler` and `server.serve` expose the same HTTP service. Platform APIs `AccessContext`, `SiteAccess`, `sign_context`, `verify_context` are described in [platform.md](platform.md).
 
 All request bodies are JSON (maximum 32 KiB). Site IDs are explicit, origins are exact and page paths must be pre-registered; query strings and hashes do not create new comment streams.
 
+Platform deployments use `serve --gateway-key-env NAME`, optionally `--session-endpoint`, `--reauth-endpoint`, `--return-path`, and `--require-existing-db`. Every non-health request needs a valid platform context, including direct backend assets; each site operation independently checks its scope. The bearer-token descriptions below refer to the retained legacy single-gateway mode, not platform authorization.
+
 | Method | Path | Behavior |
 | --- | --- | --- |
 | GET | `/health` | Version and service name |

chatcomment-0.2.1/docs/platform.md

@@ -0,0 +1,120 @@
+# Platform service integration
+
+ChatComment can run as an independent Coolify application. The platform owns
+ChatLogin accounts/sessions, project ACLs, CSRF, password reauthentication and
+native resource/deployment IDs. ChatComment owns comments, field settings,
+moderation and its persistent SQLite data. It does not schedule containers or
+duplicate account tables.
+
+## Start a scoped backend
+
+```sh
+chatcomment --db /data/comments.sqlite3 serve --host 0.0.0.0 --port 8000 \
+  --gateway-key-env CHATCOMMENT_GATEWAY_KEY \
+  --session-endpoint /__platform/session \
+  --reauth-endpoint /__platform/reauth --return-path /
+```
+
+Use a server-only randomly generated key of at least 32 characters, stored in
+the platform's secret configuration. All non-health routes, including assets
+on the direct native application domain, require a signed context. `/health`
+is the only unsigned route. This mode explicitly rejects legacy token mode;
+browser `Role`, nickname, email and Bearer headers do not grant access.
+
+`--require-existing-db` validates the existing SQLite before `Store` can initialize
+anything: header, integrity, required tables/columns and readable schema. Empty,
+corrupt, unrelated or incompatible files fail closed without source changes.
+It reads a stable private snapshot including WAL rather than creating sidecars
+beside the mounted source; valid schemas with zero comments are accepted.
+The same preflight is available as `validate_existing_database(path)`.
+
+The legacy `--token-file` mode remains for existing deployments during staged
+migration. It must not be used as a multi-user platform authorization shortcut.
+
+## Reusable Python contract
+
+```python
+from chatcomment import AccessContext, SiteAccess, sign_context
+
+# Obtain a current Session from ChatLogin ManagedUsers.sessions.resolve().
+# Read current project grants; do not derive these from Principal.role.
+context = AccessContext.from_chatlogin(
+    session,
+    session_id=stable_session_digest,
+    email=current_verified_account_email,
+    sites={site_id: SiteAccess(
+        read=may_read, comment=may_comment, manage=may_manage,
+        owner=is_site_owner, management_until=site_bound_reauth_expiry,
+    )},
+    csrf_verified=actual_request_csrf_was_verified,
+)
+headers = sign_context(
+    context, key=server_key, method=method,
+    path=backend_path_with_raw_query, body=raw_request_body,
+    ttl=30, audience='chatcomment',
+)
+```
+
+The gateway strips all incoming `X-ChatComment-*` identity headers, checks the
+current app session and site/project permission on every request, verifies
+Origin and CSRF for writes, signs the **downstream** method/path/query/raw body,
+and forwards only its generated context headers to the controlled internal
+upstream. The backend calls `verify_context` and again checks the selected site's
+permission. A context cannot be reused for a different body, verb, path or site.
+TTL is at most 60 seconds. Signed claims are server-to-server, never sent to JS
+or logged. Keep the backend path canonical and preserve raw body bytes.
+
+`AccessContext` contains `subject`, a session identifier/digest, current email,
+`sites`, `csrf_verified`, and `authenticated`. `SiteAccess` contains explicit
+`read`, `comment`, `manage`, `owner`, and absolute `management_until` time.
+Guest contexts must explicitly use `authenticated=False`; they cannot have
+management eligibility and never read private sites, even if mis-scoped.
+
+For a native in-process adapter, `make_handler(..., context_resolver=callable)`
+accepts the same validated context. The callable receives headers, method,
+downstream path and body bytes. Do not combine it with a gateway key or legacy
+global token. The independent-service CLI uses the signed transport.
+
+## Management and browser contract
+
+`/api/sites/{id}/config` returns field settings, owner hint eligibility and public
+same-origin auth endpoint paths. It never returns expected administrator email
+or a signing key. The widget sends `{site,email}` to `/api/admin/entry` only for
+an eligible owner. A matching email only reveals its single settings gear.
+
+The gear opens `/login?site={id}`. The included form posts `{site,email,password}`
+to the configured **platform** reauthentication endpoint with native session
+CSRF. The platform verifies the existing password and current owner eligibility,
+then records a 900-second grant bound to subject, reader session, project and
+site. Subsequent contexts may include that site's `management_until`.
+An email hint, global admin role, another site's grant or expired grant never
+authorizes management. `GET /api/admin/sites` lists only currently authorized,
+reauthenticated sites; site paths independently enforce the scope.
+
+Session responses supply `csrf_token`. The platform owns logout, reader session
+audiences, account disable/revision checks and current ACL revocation. A raw
+backend without platform context rejects requests. Central and reader cookies
+must not be shared across wildcard application domains.
+
+## Persistent migration
+
+Keep the existing `site_id` and `page_key` explicit when frontend domains or URI
+change. Mount the existing local data directory at `/data` using its real UID
+and restrictive permissions. SQLite WAL permits a staged period with the old
+service using the same authoritative file; do not create diverging copies.
+Coolify's native storage/resource configuration owns this mount and lifecycle.
+
+Before deployment, take an online SQLite backup and generate per-row hashes of
+all columns in `sites` and `comments`, including private email and soft-deleted
+states. Compare the original IDs/rows after migration and permit only recorded
+new rows. If the new app origin differs, add it explicitly:
+
+```sh
+chatcomment --db /data/comments.sqlite3 site allow-origin personal-ai https://new-app.example
+```
+
+This changes only the registered origin list. Field/anonymous/moderation settings
+and every comment row remain unchanged. Record that intentional site metadata
+change separately. Preserve the old service/route until the new same-page
+browser flow, independent readback, permissions and native restart/redeploy
+persistence pass. Retiring legacy routing is a separate coordinated last step.

{chatcomment-0.1.1 → chatcomment-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ChatComment"
-version = "0.1.1"
+version = "0.2.1"
 description = "Embeddable comments with a Python server, SQLite storage and a small JavaScript widget."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -19,7 +19,7 @@ Repository = "https://github.com/ChatArch/ChatComment"
 chatcomment = "chatcomment.cli:main"
 
 [project.optional-dependencies]
-dev = ["build", "pytest>=8", "twine"]
+dev = ["build", "pytest>=8", "twine", "chatlogin>=0.2.1,<0.3.0"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{chatcomment-0.1.1 → chatcomment-0.2.1}/src/ChatComment.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ChatComment
-Version: 0.1.1
+Version: 0.2.1
 Summary: Embeddable comments with a Python server, SQLite storage and a small JavaScript widget.
 Author: ChatArch
 License-Expression: MIT
@@ -15,6 +15,7 @@ Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Requires-Dist: chatlogin<0.3.0,>=0.2.1; extra == "dev"
 Dynamic: license-file
 
 # ChatComment
@@ -43,6 +44,8 @@ chatcomment serve --token-file ~/.chatarch/chatcomment/admin-token
 
 API、网关接入、备份与恢复见 [docs/api.md](docs/api.md)、[docs/deployment.md](docs/deployment.md)。本包不自动开放防火墙或注册 DNS，也不包含云服务凭据。
 
+多用户平台接入使用 [平台服务协议](docs/platform.md)：`--gateway-key-env` 启用按主体/session/站点校验的签名上下文，所有非 health 路由均拒绝未签名访问，兼容独立 Coolify 资源。`AccessContext.from_chatlogin()` 复用已验证的 ChatLogin Session；项目 ACL 与密码二次验证由平台拥有，账户全局 admin 不能自动获得站点权限。旧 `--token-file` 模式仅保留给已有单网关部署迁移使用。
+
 独立留言板为 `/board?site=personal-blog&page=%2Fpost%2Fone`，与嵌入表单读写同一留言流。组件只提供一个齿轮入口：已登录 owner 在邮箱栏填写匹配邮箱后，服务器返回显示提示；昵称不参与判断，邮箱不下发到 JS 配置。齿轮指向邮箱/密码验证页；网关须实现 `/api/admin/reauth` 并在校验现有账号后授予短时管理权限。公开站点没有该提示。
 
 网关为普通成员设置 `X-ChatComment-Role: reader`，仅经服务端验证的 owner 使用 `admin`；管理接口另行验证权限。公开浏览器不能靠昵称、邮箱或伪造角色 header 获得权限，因为缺少服务器 Bearer token。服务器可为受信 owner 请求附加 `X-ChatComment-Admin-Email`，只用于入口提示。完整验证合约见部署文档。

{chatcomment-0.1.1 → chatcomment-0.2.1}/src/ChatComment.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ README.md
 pyproject.toml
 docs/api.md
 docs/deployment.md
+docs/platform.md
 src/ChatComment.egg-info/PKG-INFO
 src/ChatComment.egg-info/SOURCES.txt
 src/ChatComment.egg-info/dependency_links.txt
@@ -13,13 +14,19 @@ src/ChatComment.egg-info/entry_points.txt
 src/ChatComment.egg-info/requires.txt
 src/ChatComment.egg-info/top_level.txt
 src/chatcomment/__init__.py
+src/chatcomment/access.py
 src/chatcomment/cli.py
 src/chatcomment/server.py
 src/chatcomment/store.py
+src/chatcomment/validation.py
 src/chatcomment/static/admin.html
 src/chatcomment/static/board.html
 src/chatcomment/static/login.html
 src/chatcomment/static/widget.css
 src/chatcomment/static/widget.js
 tests/cli-tests/test_cli.py
-tests/code-tests/test_comments.py
+tests/code-tests/test_access.py
+tests/code-tests/test_chatlogin_adapter.py
+tests/code-tests/test_comments.py
+tests/code-tests/test_platform_http.py
+tests/code-tests/test_validation.py

{chatcomment-0.1.1 → chatcomment-0.2.1}/src/ChatComment.egg-info/requires.txt

@@ -6,3 +6,4 @@ chatenv<0.3.0,>=0.2.11
 build
 pytest>=8
 twine
+chatlogin<0.3.0,>=0.2.1

chatcomment-0.2.1/src/chatcomment/__init__.py

@@ -0,0 +1,8 @@
+"""Reusable comments storage and HTTP service."""
+__version__ = "0.2.1"
+
+from .store import Store
+from .access import AccessContext,SiteAccess,sign_context,verify_context
+from .validation import validate_existing_database
+
+__all__ = ["Store", "AccessContext", "SiteAccess", "sign_context", "verify_context", "validate_existing_database", "__version__"]

chatcomment-0.2.1/src/chatcomment/access.py

@@ -0,0 +1,150 @@
+"""Platform-neutral, per-site permissions and a signed gateway transport.
+
+The platform resolves the real ChatLogin session on EVERY request, evaluates its
+site ACL and CSRF, then signs this context. No global account role implies site
+access. Browser-supplied identity headers are not trusted by this module.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import asdict, dataclass, field
+import hashlib
+import hmac
+import json
+import math
+import secrets
+import time
+from typing import Mapping
+from types import MappingProxyType
+
+
+@dataclass(frozen=True)
+class SiteAccess:
+    read: bool = False
+    comment: bool = False
+    manage: bool = False
+    owner: bool = False
+    management_until: float = 0
+
+    def __post_init__(self):
+        if any(type(getattr(self,k)) is not bool for k in ['read','comment','manage','owner']):
+            raise ValueError('Site permissions must be booleans')
+        if (self.comment or self.manage or self.owner) and not self.read:
+            raise ValueError('Site operations require explicit site read permission')
+        if self.owner and not self.manage:
+            raise ValueError('Site owner must have explicit management eligibility')
+        if type(self.management_until) not in (int,float) or not math.isfinite(self.management_until):
+            raise ValueError('Invalid management grant expiry')
+
+
+@dataclass(frozen=True)
+class AccessContext:
+    subject: str
+    session: str  # A stable session digest/identifier, never the raw cookie.
+    email: str = field(default='',repr=False)
+    sites: Mapping[str, SiteAccess] = field(default_factory=dict)
+    csrf_verified: bool = False
+    authenticated: bool = True
+
+    def __post_init__(self):
+        for name in ['subject','session']:
+            value=getattr(self,name)
+            if not isinstance(value,str) or not 1<=len(value)<=256:
+                raise ValueError('Authenticated subject and session identifier required')
+        if not isinstance(self.email,str) or len(self.email)>500 or type(self.csrf_verified) is not bool or type(self.authenticated) is not bool:
+            raise ValueError('Invalid identity or CSRF context')
+        if not isinstance(self.sites,Mapping) or len(self.sites)>100:
+            raise ValueError('Bounded per-site permissions required')
+        for site,scope in self.sites.items():
+            if not isinstance(site,str) or not 1<=len(site)<=64 or not isinstance(scope,SiteAccess):
+                raise ValueError('Invalid site permission')
+            if not self.authenticated and (scope.manage or scope.owner):
+                raise ValueError('Anonymous context cannot have management eligibility')
+        object.__setattr__(self,'sites',MappingProxyType(dict(self.sites)))
+
+    def scope(self,site_id):
+        return self.sites.get(site_id,SiteAccess())
+
+    def permits(self,site_id,action,*,now=None):
+        scope=self.scope(site_id)
+        if action=='read':return scope.read
+        if action=='comment':return scope.read and scope.comment
+        if action=='hint':return self.authenticated and scope.read and scope.owner
+        if action=='manage':
+            return self.authenticated and scope.read and scope.manage and scope.management_until>(time.time() if now is None else now)
+        return False
+
+    def require(self,site_id,action,*,write=False,now=None):
+        if not self.permits(site_id,action,now=now):
+            raise PermissionError('此账号未获该站点权限或需要重新验证密码')
+        if write and not self.csrf_verified:
+            raise PermissionError('平台未验证此请求的 CSRF')
+
+    @classmethod
+    def from_chatlogin(cls,session,*,session_id,email,sites,csrf_verified=False):
+        """Adapt an already-resolved ChatLogin Session, never infer ACL from Role."""
+        principal=session.principal
+        if not principal.authenticated:
+            raise PermissionError('需要已验证的 ChatLogin 主体')
+        return cls(principal.user_id,session_id,email,sites,csrf_verified)
+
+
+def _key(value):
+    if isinstance(value,str):value=value.encode()
+    if not isinstance(value,bytes) or len(value)<32:
+        raise ValueError('Gateway signing key must be at least 32 bytes')
+    return value
+
+
+def _binding(method,path,body):
+    if not isinstance(body,bytes) or not isinstance(path,str) or not path.startswith('/'):
+        raise ValueError('Canonical request path and raw body bytes required')
+    return {'method':method.upper(),'path':path,'body_sha256':hashlib.sha256(body).hexdigest()}
+
+
+def sign_context(context:AccessContext,*,key,method,path,body=b'',now=None,ttl=30,audience='chatcomment'):
+    """Return server-to-server headers bound to a single HTTP request.
+
+    Gateway MUST strip incoming X-ChatComment-* headers first. Password checks,
+    current account/session revocation, site ACL and CSRF happen in the platform.
+    """
+    if not isinstance(context,AccessContext):raise TypeError('Verified AccessContext required')
+    if type(ttl) is not int or not 1<=ttl<=60:raise ValueError('Context TTL must be 1..60 seconds')
+    stamp=time.time() if now is None else now
+    if type(stamp) not in (int,float) or not math.isfinite(stamp):raise ValueError('Invalid signing clock')
+    value={'v':1,'aud':audience,'iat':stamp,'exp':stamp+ttl,'nonce':secrets.token_urlsafe(16),
+           'subject':context.subject,'session':context.session,'email':context.email,
+           'sites':{site:asdict(scope) for site,scope in context.sites.items()},
+           'csrf_verified':context.csrf_verified,'authenticated':context.authenticated,**_binding(method,path,body)}
+    raw=json.dumps(value,ensure_ascii=False,separators=(',',':'),sort_keys=True).encode()
+    encoded=base64.urlsafe_b64encode(raw).decode().rstrip('=')
+    if len(encoded)>16000:raise ValueError('Gateway context is too large; scope it to this request')
+    signature=hmac.new(_key(key),encoded.encode(),hashlib.sha256).hexdigest()
+    return {'X-ChatComment-Context':encoded,'X-ChatComment-Signature':signature}
+
+
+def verify_context(headers,*,key,method,path,body=b'',now=None,audience='chatcomment'):
+    """Validate context before using any identity or site permission claim."""
+    encoded=headers.get('X-ChatComment-Context')
+    signature=headers.get('X-ChatComment-Signature')
+    if encoded is None and signature is None:return None
+    if not isinstance(encoded,str) or not 1<=len(encoded)<=16000 or not isinstance(signature,str) or len(signature)!=64 or not signature.isascii():
+        raise PermissionError('无效的平台认证上下文')
+    try:encoded_bytes=encoded.encode('ascii','strict')
+    except UnicodeError as exc:raise PermissionError('无效的平台认证上下文') from exc
+    expected=hmac.new(_key(key),encoded_bytes,hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected,signature):raise PermissionError('平台认证签名不正确')
+    try:
+        raw=base64.b64decode(encoded+'='*((-len(encoded))%4),altchars=b'-_',validate=True)
+        data=json.loads(raw)
+        stamp=time.time() if now is None else now
+        if data['v']!=1 or data['aud']!=audience:raise ValueError('Wrong audience')
+        issued,expires=data['iat'],data['exp']
+        if any(type(v) not in (int,float) or not math.isfinite(v) for v in [issued,expires,stamp]):raise ValueError('Invalid timestamp')
+        if not issued-5<=stamp<expires or not 0<expires-issued<=60:raise ValueError('Expired context')
+        for name,value in _binding(method,path,body).items():
+            if data[name]!=value:raise ValueError('Request binding mismatch')
+        scopes={site:SiteAccess(**scope) for site,scope in data['sites'].items()}
+        return AccessContext(data['subject'],data['session'],data['email'],scopes,data['csrf_verified'],data['authenticated'])
+    except (ValueError,TypeError,KeyError,AttributeError) as exc:
+        raise PermissionError('平台认证上下文无效、过期或请求不匹配') from exc

chatcomment-0.2.1/src/chatcomment/cli.py

@@ -0,0 +1,106 @@
+"""Thin CLI around the Python API."""
+from pathlib import Path
+import json
+import os
+
+import click
+from chatstyle import add_tree_option
+
+from . import Store, __version__
+from .validation import validate_existing_database
+
+
+@click.group(name='chatcomment')
+@click.version_option(__version__, prog_name='chatcomment')
+@add_tree_option()
+@click.option('--db', type=click.Path(path_type=Path), default=Path('~/.chatarch/chatcomment/comments.sqlite3'), show_default=True)
+@click.pass_context
+def main(ctx, db):
+    """Embeddable comments, site settings and persistent storage."""
+    ctx.ensure_object(dict)
+    ctx.obj['db'] = db
+
+
+@main.command()
+@click.option('--host', default='127.0.0.1', show_default=True)
+@click.option('--port', default=10196, type=click.IntRange(1,65535), show_default=True)
+@click.option('--token-file', type=click.Path(exists=True, dir_okay=False, path_type=Path), help='Legacy single-gateway token mode.')
+@click.option('--gateway-key-file', type=click.Path(exists=True,dir_okay=False,path_type=Path), help='Server-only signing key; enables per-site platform authorization.')
+@click.option('--gateway-key-env', help='Name of environment variable holding the server-only signing key.')
+@click.option('--session-endpoint', default='/api/session',show_default=True)
+@click.option('--reauth-endpoint', default=None,help='Platform same-origin management reauthentication endpoint.')
+@click.option('--return-path', default='/',show_default=True)
+@click.option('--require-existing-db',is_flag=True,help='Validate a readable existing ChatComment SQLite database before initialization.')
+@click.pass_context
+def serve(ctx, host, port, token_file,gateway_key_file,gateway_key_env,session_endpoint,reauth_endpoint,return_path,require_existing_db):
+    """Serve API, widget assets and the gateway-protected admin page."""
+    from .server import serve as run
+    if sum(bool(v) for v in [token_file,gateway_key_file,gateway_key_env])!=1:
+        raise click.UsageError('Choose exactly one of --token-file, --gateway-key-file or --gateway-key-env.')
+    token=token_file.read_text().strip() if token_file else None
+    key=gateway_key_file.read_text().strip() if gateway_key_file else os.environ.get(gateway_key_env,'') if gateway_key_env else None
+    if len(token if token is not None else key or '')<32:
+        raise click.ClickException('Server credential must contain at least 32 characters.')
+    if require_existing_db:
+        try:
+            validate_existing_database(ctx.obj['db'])
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
+    run(Store(ctx.obj['db']), token=token,gateway_key=key, host=host, port=port,
+        session_endpoint=session_endpoint,reauth_endpoint=reauth_endpoint,return_path=return_path)
+
+
+@main.group()
+def site():
+    """Register sites and inspect settings."""
+
+
+@site.command(name='register')
+@click.argument('site_id')
+@click.option('--title', default='留言')
+@click.option('--origin', 'origins', required=True, multiple=True)
+@click.option('--page', 'pages', required=True, multiple=True)
+@click.option('--public', is_flag=True, help='Explicitly allow public comment reads and anonymous writes.')
+@click.pass_context
+def register(ctx, site_id, title, origins, pages, public):
+    """Register an exact site ID, origin allowlist and allowed page paths."""
+    try:
+        result = Store(ctx.obj['db']).register(site_id,title=title,origins=list(origins),pages=list(pages),private=not public)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(json.dumps(result,ensure_ascii=False,indent=2))
+
+
+@site.command(name='list')
+@click.pass_context
+def list_sites(ctx):
+    """List registered sites and their effective settings."""
+    click.echo(json.dumps(Store(ctx.obj['db']).sites(),ensure_ascii=False,indent=2))
+
+
+@site.command(name='allow-origin')
+@click.argument('site_id')
+@click.argument('origin')
+@click.pass_context
+def allow_origin(ctx,site_id,origin):
+    """Add an approved platform origin, preserving comments and field settings."""
+    try:
+        result=Store(ctx.obj['db']).allow_origin(site_id,origin)
+    except (ValueError,KeyError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(json.dumps(result,ensure_ascii=False,indent=2))
+
+
+@main.command()
+@click.argument('destination', type=click.Path(path_type=Path))
+@click.pass_context
+def backup(ctx, destination):
+    """Create a consistent SQLite online backup without overwriting a file."""
+    try:
+        click.echo(Store(ctx.obj['db']).backup(destination))
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+if __name__ == '__main__':
+    main()