ChatLogin 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. {chatlogin-0.2.0 → chatlogin-0.2.2}/CHANGELOG.md +14 -0
  2. {chatlogin-0.2.0 → chatlogin-0.2.2}/DEVELOP.md +9 -0
  3. chatlogin-0.2.2/MANIFEST.in +13 -0
  4. {chatlogin-0.2.0/src/ChatLogin.egg-info → chatlogin-0.2.2}/PKG-INFO +7 -2
  5. {chatlogin-0.2.0 → chatlogin-0.2.2}/README.en.md +6 -1
  6. {chatlogin-0.2.0 → chatlogin-0.2.2}/README.md +6 -1
  7. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/capability-map.en.md +3 -0
  8. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/capability-map.md +2 -0
  9. chatlogin-0.2.2/docs/frontend.en.md +96 -0
  10. chatlogin-0.2.2/docs/frontend.md +96 -0
  11. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/index.en.md +2 -0
  12. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/index.md +2 -0
  13. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/integration.en.md +4 -0
  14. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/integration.md +4 -0
  15. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/interface-tree.en.md +5 -0
  16. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/interface-tree.md +5 -0
  17. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/managed-users.en.md +2 -0
  18. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/managed-users.md +2 -0
  19. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/quickstart.en.md +2 -0
  20. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/quickstart.md +2 -0
  21. chatlogin-0.2.2/docs/service-onboarding.en.md +84 -0
  22. chatlogin-0.2.2/docs/service-onboarding.md +99 -0
  23. chatlogin-0.2.2/examples/frontend/README.md +7 -0
  24. chatlogin-0.2.2/examples/frontend/react.tsx +16 -0
  25. chatlogin-0.2.2/examples/frontend/vanilla.ts +26 -0
  26. chatlogin-0.2.2/examples/managed_service.py +59 -0
  27. {chatlogin-0.2.0 → chatlogin-0.2.2}/mkdocs.yml +4 -0
  28. chatlogin-0.2.2/packages/chatlogin/LICENSE +21 -0
  29. chatlogin-0.2.2/packages/chatlogin/README.md +85 -0
  30. chatlogin-0.2.2/packages/chatlogin/package-lock.json +124 -0
  31. chatlogin-0.2.2/packages/chatlogin/package.json +39 -0
  32. chatlogin-0.2.2/packages/chatlogin/scripts/build.mjs +30 -0
  33. chatlogin-0.2.2/packages/chatlogin/scripts/http_contract.py +107 -0
  34. chatlogin-0.2.2/packages/chatlogin/scripts/pack-check.mjs +53 -0
  35. chatlogin-0.2.2/packages/chatlogin/src/client.ts +281 -0
  36. chatlogin-0.2.2/packages/chatlogin/src/index.ts +2 -0
  37. chatlogin-0.2.2/packages/chatlogin/src/react.tsx +144 -0
  38. chatlogin-0.2.2/packages/chatlogin/src/ui.ts +33 -0
  39. chatlogin-0.2.2/packages/chatlogin/styles/account-menu.css +19 -0
  40. chatlogin-0.2.2/packages/chatlogin/tests/client.test.mjs +204 -0
  41. chatlogin-0.2.2/packages/chatlogin/tests/default-page.test.mjs +77 -0
  42. chatlogin-0.2.2/packages/chatlogin/tests/fixtures/http-contract.json +365 -0
  43. chatlogin-0.2.2/packages/chatlogin/tests/react.test.mjs +107 -0
  44. chatlogin-0.2.2/packages/chatlogin/tests/tsconfig.json +5 -0
  45. chatlogin-0.2.2/packages/chatlogin/tests/types.test.tsx +21 -0
  46. chatlogin-0.2.2/packages/chatlogin/tsconfig.json +10 -0
  47. {chatlogin-0.2.0 → chatlogin-0.2.2/src/ChatLogin.egg-info}/PKG-INFO +7 -2
  48. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/ChatLogin.egg-info/SOURCES.txt +35 -0
  49. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/__init__.py +1 -1
  50. chatlogin-0.2.2/src/chatlogin/account_ui.py +59 -0
  51. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo.py +1 -1
  52. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/managed.html +1 -5
  53. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/fastapi.py +44 -1
  54. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/managed_demo.py +7 -10
  55. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/managed_web.py +32 -2
  56. chatlogin-0.2.2/src/chatlogin/web/assets/account-menu.css +19 -0
  57. chatlogin-0.2.2/src/chatlogin/web/assets/client.js +282 -0
  58. chatlogin-0.2.2/src/chatlogin/web/assets/login.css +67 -0
  59. chatlogin-0.2.2/src/chatlogin/web/assets/login.js +36 -0
  60. chatlogin-0.2.2/src/chatlogin/web/assets/ui.js +35 -0
  61. chatlogin-0.2.2/src/chatlogin/web/templates/chatlogin/account-menu.html +10 -0
  62. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/login.html +1 -1
  63. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/profile.html +2 -1
  64. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/users.html +2 -1
  65. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_demo_release_contract.py +16 -0
  66. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_live_login_service.py +2 -1
  67. chatlogin-0.2.2/tests/code-tests/test_onboarding_acceptance.py +67 -0
  68. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_packaging_imports.py +2 -2
  69. chatlogin-0.2.2/tests/code-tests/test_service_onboarding.py +149 -0
  70. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_ui_contract.py +4 -2
  71. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_web.py +6 -2
  72. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_version.py +1 -1
  73. chatlogin-0.2.0/MANIFEST.in +0 -7
  74. chatlogin-0.2.0/src/chatlogin/web/assets/login.js +0 -67
  75. {chatlogin-0.2.0 → chatlogin-0.2.2}/LICENSE +0 -0
  76. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/chatvoice-managed.en.md +0 -0
  77. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/chatvoice-managed.md +0 -0
  78. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/cli-tree.en.md +0 -0
  79. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/cli-tree.md +0 -0
  80. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/demo.en.md +0 -0
  81. {chatlogin-0.2.0 → chatlogin-0.2.2}/docs/demo.md +0 -0
  82. {chatlogin-0.2.0 → chatlogin-0.2.2}/examples/demo_fastapi.py +0 -0
  83. {chatlogin-0.2.0 → chatlogin-0.2.2}/examples/quickstart_fastapi.py +0 -0
  84. {chatlogin-0.2.0/src/chatlogin/web/assets → chatlogin-0.2.2/packages/chatlogin/styles}/login.css +0 -0
  85. {chatlogin-0.2.0 → chatlogin-0.2.2}/pyproject.toml +0 -0
  86. {chatlogin-0.2.0 → chatlogin-0.2.2}/setup.cfg +0 -0
  87. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/ChatLogin.egg-info/dependency_links.txt +0 -0
  88. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/ChatLogin.egg-info/entry_points.txt +0 -0
  89. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/ChatLogin.egg-info/requires.txt +0 -0
  90. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/ChatLogin.egg-info/top_level.txt +0 -0
  91. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/backends/__init__.py +0 -0
  92. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/backends/chatvoice.py +0 -0
  93. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/backends/chatvoice_managed.py +0 -0
  94. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/cli.py +0 -0
  95. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/config.py +0 -0
  96. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/credentials.py +0 -0
  97. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/__init__.py +0 -0
  98. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo-login.css +0 -0
  99. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo-login.js +0 -0
  100. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo.css +0 -0
  101. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo.js +0 -0
  102. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/headless.html +0 -0
  103. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/home.html +0 -0
  104. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/templates.html +0 -0
  105. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/workspace.html +0 -0
  106. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/identity.py +0 -0
  107. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/managed.py +0 -0
  108. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/paths.py +0 -0
  109. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/private_sqlite.py +0 -0
  110. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/security.py +0 -0
  111. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/sessions.py +0 -0
  112. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/sqlite.py +0 -0
  113. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/ui.py +0 -0
  114. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/user_ui.py +0 -0
  115. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/__init__.py +0 -0
  116. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/assets/users.css +0 -0
  117. {chatlogin-0.2.0 → chatlogin-0.2.2}/src/chatlogin/web/assets/users.js +0 -0
  118. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/cli-tests/README.md +0 -0
  119. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/README.md +0 -0
  120. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_async_credentials.py +0 -0
  121. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_chatvoice_backend.py +0 -0
  122. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_chatvoice_managed_backend.py +0 -0
  123. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_core.py +0 -0
  124. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_core_guards.py +0 -0
  125. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_demo_multiuser.py +0 -0
  126. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_demo_site.py +0 -0
  127. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_demo_ux.py +0 -0
  128. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_http_guards.py +0 -0
  129. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_concurrency.py +0 -0
  130. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_demo.py +0 -0
  131. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_form_safety.py +0 -0
  132. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_integration.py +0 -0
  133. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_journal_race.py +0 -0
  134. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_plugin.py +0 -0
  135. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_read_snapshot.py +0 -0
  136. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_sessions.py +0 -0
  137. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_ui.py +0 -0
  138. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_users.py +0 -0
  139. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_managed_web.py +0 -0
  140. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_origin_mount.py +0 -0
  141. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_packaging_demo.py +0 -0
  142. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_scaffold_contract.py +0 -0
  143. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_session_purge.py +0 -0
  144. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_sqlite_security.py +0 -0
  145. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/code-tests/test_storage_platform.py +0 -0
  146. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/conftest.py +0 -0
  147. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/mock-cli-tests/README.md +0 -0
  148. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_cli.py +0 -0
  149. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_docs_deployment.py +0 -0
  150. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_managed_cli.py +0 -0
  151. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_managed_docs.py +0 -0
  152. {chatlogin-0.2.0 → chatlogin-0.2.2}/tests/test_paths_cli.py +0 -0
@@ -1,5 +1,19 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.2.2 — 2026-11-17
4
+
5
+ - 新增源码 npm 包 `@chatarch/chatlogin`(0.1.0):无运行时依赖的同源 TypeScript 客户端,覆盖 schema v1 发现、会话、登录、退出和 fresh-CSRF 请求;可选 React 18/19 子入口提供登录与账号菜单。
6
+ - Python 默认登录页复用同一 TypeScript 客户端生成的浏览器模块;CSS 保持 Python 资源单源,同步到 npm 包,并增加漂移检查、真实 ASGI fixtures、干净 tarball 消费者及独立前端 CI。
7
+ - 默认 `login.js` 改为 ES module;FastAPI 与包内整页示例已同步。自定义 HTTP/标准库宿主采用新模板时须同源提供 `client.js`、`ui.js` 并使用 module script;此模板迁移要求独立于 npm 对已发布 Python 0.2.1 JSON/schema v1 的兼容。
8
+ - 登录/退出在同一客户端实例串行,避免在途登录晚于退出恢复 Cookie;固定账号、托管角色和 headless 能力分别呈现。Python 的密码、会话、权限边界与 CLI 保持不变,不引入跨站 SSO、共享 Cookie 或 Node 认证后端。
9
+ - 增加中英文前端接入文档与无框架/React 示例;npm 采用独立的 `npm-v0.1.0` 标签与 Trusted Publishing 工作流;Python 通过 `v0.2.2` 标签沿用 PyPI OIDC 发布。
10
+
11
+ ## 0.2.1 — 2026-10-14
12
+
13
+ - 新增 Host 校验、no-store 的 `GET {prefix}/api`,按真实路由和可信 ASGI mount 发现操作、页面和能力;headless 不声明页面。
14
+ - 新增可组合 `AccountMenuUI` 齿轮/链接片段、scoped CSS 和角色感知导航;默认用户管理、本人资料和 managed demo 宿主页复用。
15
+ - 新增无默认生产账号的新服务 factory 示例与中英文接入说明;保持既有请求、CSRF、Origin、角色和 URL 契约。
16
+
3
17
  ## 0.2.0 — 2026-10-11
4
18
 
5
19
  - 新增应用显式采用的 managed users 接入面:首个 owner 的环境变量 bootstrap、`ManagedUsers` / `create_managed_auth` 指引、owner/admin/user 角色矩阵,以及默认登录、用户管理和本人资料路由说明。
@@ -20,6 +20,15 @@
20
20
  - Keep `README.md`, `docs/`, and `CHANGELOG.md` in sync with user-facing changes.
21
21
  - Keep managed-user CLI trees and bilingual `managed-users` guidance synchronized with actual registered commands and provider APIs.
22
22
 
23
+ ## Frontend Package
24
+
25
+ - Keep the framework-neutral client under `packages/chatlogin/src/client.ts`; React stays in the optional `@chatarch/chatlogin/react` subpath. Never add frontend credential/session persistence or Node authentication policy.
26
+ - Build with `cd packages/chatlogin && npm ci --ignore-scripts && npm run build`. Commit generated Python `web/assets/client.js` and `ui.js`; Python installation must not require Node.
27
+ - Python `web/assets/login.css` and `account-menu.css` are the CSS source. Build copies them to npm `styles/`; do not edit the copies directly.
28
+ - Verify `python packages/chatlogin/scripts/http_contract.py --check` in a Python environment with `ChatLogin[web]` plus the test transport `httpx>=0.27,<1.0`, then package-local `npm run check:shared`, `npm test`, `npm run typecheck`, and `npm run pack:check`. HTTPX is a test dependency, not a production web requirement.
29
+ - When changing the HTTP contract, regenerate fixtures with `python packages/chatlogin/scripts/http_contract.py`, review the diff, and update docs and both frontends together. Same-origin Cookie/CSRF and server-side authorization remain authoritative.
30
+ - Registry publishing is a distinct reviewed release. Do not equate a source commit, local tarball, or green package CI with an npm release.
31
+
23
32
  ## Automation
24
33
 
25
34
  - Keep automation small and reviewable.
@@ -0,0 +1,13 @@
1
+ include README.en.md CHANGELOG.md DEVELOP.md mkdocs.yml
2
+ recursive-include tests *.py *.md
3
+ recursive-include examples *.py
4
+ recursive-include examples/frontend *.ts *.tsx *.md
5
+ recursive-include packages/chatlogin/src *.ts *.tsx
6
+ recursive-include packages/chatlogin/scripts *.mjs *.py
7
+ recursive-include packages/chatlogin/tests *.mjs *.ts *.tsx *.json
8
+ recursive-include packages/chatlogin/styles *.css
9
+ include packages/chatlogin/package.json packages/chatlogin/package-lock.json packages/chatlogin/tsconfig.json packages/chatlogin/README.md packages/chatlogin/LICENSE
10
+ recursive-include docs *.md
11
+ recursive-include src/chatlogin/web *.html *.css *.js
12
+ recursive-include src/chatlogin/demo_site *.html *.css *.js
13
+ global-exclude __pycache__ *.py[cod]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ChatLogin
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: Reusable authentication, sessions, and login templates for Python-backed websites.
5
5
  Author-email: ChatArch <1073853456@qq.com>
6
6
  License-Expression: MIT
@@ -73,6 +73,7 @@ ChatLogin 是面向应用的可内嵌认证插件/集成组件,而不是独
73
73
  | 应用自管 owner/admin/user | [托管用户](docs/managed-users.md) |
74
74
  | 既有 ChatVoice 账号库接入管理 | [ChatVoice legacy schema 集成](docs/chatvoice-managed.md) |
75
75
  | 默认 UI、模板覆盖与 headless | [能力地图](docs/capability-map.md) |
76
+ | TypeScript 客户端与可选 React 组件 | [前端接入](docs/frontend.md) |
76
77
  | CLI 版本和命令树 | [CLI 树](docs/cli-tree.md) |
77
78
 
78
79
  ## 安装
@@ -105,7 +106,11 @@ chatlogin serve --host 127.0.0.1 --port 8765 --origin https://login.example.com
105
106
 
106
107
  核心包不要求网站采用包内页面。已有静态 HTML/原生 JS 的网站可以只挂载 JSON 路由,继续保留原登录入口和用户数据库;标准库 HTTP 宿主也可以只使用 `LoginUI` 渲染登录页。
107
108
 
108
- ## 托管用户(0.2.0)
109
+ ## 托管用户(0.2.1)
110
+
111
+ 自有 JS/TS 前端可使用源码包 [`@chatarch/chatlogin`](packages/chatlogin/README.md):无框架客户端覆盖发现、会话、登录、退出与 CSRF 请求,React 组件通过可选子入口复用。默认 Python 页与 npm 共用客户端和样式;Python 继续负责认证与授权。包的 registry 发布按独立 npm 流程进行,本变更不自动发布。Headlamp 等 Go 应用仍可通过 Python HTTP 认证代理接入,不要求双方使用同一种语言。见[前端接入](docs/frontend.md)。
112
+
113
+ 新服务可通过 `GET {prefix}/api` 发现真实注册路由,并把 `AccountMenuUI` 齿轮/链接菜单放进宿主页;完整 factory、`/admin` 前缀、headless 与自有模板示例见[新服务接入](docs/service-onboarding.md)。这不是跨服务 SSO。
109
114
 
110
115
  需要应用内 owner/admin/user、登录页、本人资料和用户管理时,新消费者显式采用 `ChatLogin>=0.2.0,<0.3.0`,并使用 `ManagedUsers` 与 `create_managed_auth`。第一个 owner 必须由操作员执行 `chatlogin users bootstrap USERNAME --instance NAME --password-env KEY` 创建;KEY 是环境变量名,绝不把密码放进 argv。它只允许空实例首次初始化,没有迁移、`--force` 或默认生产凭据。见[托管用户指南](docs/managed-users.md)。
111
116
 
@@ -27,6 +27,7 @@ Documentation: <https://arch.gh.wzhecnu.cn/ChatLogin/en/>
27
27
  | Application-owned owner/admin/user directory | [Managed Users](docs/managed-users.en.md) |
28
28
  | Existing ChatVoice account database with management | [ChatVoice legacy schema integration](docs/chatvoice-managed.en.md) |
29
29
  | Default UI, overrides, and headless mode | [Capability Map](docs/capability-map.en.md) |
30
+ | TypeScript client and optional React components | [Frontend Integration](docs/frontend.en.md) |
30
31
  | CLI version and command tree | `docs/cli-tree.en.md` |
31
32
 
32
33
  ## Install
@@ -59,7 +60,11 @@ chatlogin serve --host 127.0.0.1 --port 8765 --origin https://login.example.com
59
60
 
60
61
  The core package does not require adopting the packaged page. An existing static HTML/vanilla-JS site can mount only JSON routes and retain its current entry page and user database; a standard-library HTTP host can use `LoginUI` for rendering without installing FastAPI.
61
62
 
62
- ## Managed Users (0.2.0)
63
+ ## Managed Users (0.2.1)
64
+
65
+ Custom JS/TS frontends can use the source package [`@chatarch/chatlogin`](packages/chatlogin/README.md): a framework-neutral discovery/session/login/logout/CSRF client with an optional React entry. The Python page and npm share client code and styles; Python remains responsible for authentication and authorization. Registry publishing is a separate npm release step, not an automatic part of this source change. Go applications such as Headlamp can still use a Python HTTP authentication proxy without a language match. See [Frontend Integration](docs/frontend.en.md).
66
+
67
+ New services can discover registered routes through `GET {prefix}/api` and embed the `AccountMenuUI` gear/links fragment. See [New Service Onboarding](docs/service-onboarding.en.md) for a complete factory, `/admin` prefix, headless and host-template options. This is not cross-service SSO.
63
68
 
64
69
  For an application-owned owner/admin/user directory, login, profile, and user management, new consumers explicitly adopt `ChatLogin>=0.2.0,<0.3.0` with `ManagedUsers` and `create_managed_auth`. An operator creates the first owner with `chatlogin users bootstrap USERNAME --instance NAME --password-env KEY`; KEY is an environment-variable name, never a password in argv. Bootstrap works only for an empty instance and has no migration, `--force`, or default production credential. See [Managed Users](docs/managed-users.en.md).
65
70
 
@@ -27,6 +27,7 @@ ChatLogin 是面向应用的可内嵌认证插件/集成组件,而不是独
27
27
  | 应用自管 owner/admin/user | [托管用户](docs/managed-users.md) |
28
28
  | 既有 ChatVoice 账号库接入管理 | [ChatVoice legacy schema 集成](docs/chatvoice-managed.md) |
29
29
  | 默认 UI、模板覆盖与 headless | [能力地图](docs/capability-map.md) |
30
+ | TypeScript 客户端与可选 React 组件 | [前端接入](docs/frontend.md) |
30
31
  | CLI 版本和命令树 | [CLI 树](docs/cli-tree.md) |
31
32
 
32
33
  ## 安装
@@ -59,7 +60,11 @@ chatlogin serve --host 127.0.0.1 --port 8765 --origin https://login.example.com
59
60
 
60
61
  核心包不要求网站采用包内页面。已有静态 HTML/原生 JS 的网站可以只挂载 JSON 路由,继续保留原登录入口和用户数据库;标准库 HTTP 宿主也可以只使用 `LoginUI` 渲染登录页。
61
62
 
62
- ## 托管用户(0.2.0)
63
+ ## 托管用户(0.2.1)
64
+
65
+ 自有 JS/TS 前端可使用源码包 [`@chatarch/chatlogin`](packages/chatlogin/README.md):无框架客户端覆盖发现、会话、登录、退出与 CSRF 请求,React 组件通过可选子入口复用。默认 Python 页与 npm 共用客户端和样式;Python 继续负责认证与授权。包的 registry 发布按独立 npm 流程进行,本变更不自动发布。Headlamp 等 Go 应用仍可通过 Python HTTP 认证代理接入,不要求双方使用同一种语言。见[前端接入](docs/frontend.md)。
66
+
67
+ 新服务可通过 `GET {prefix}/api` 发现真实注册路由,并把 `AccountMenuUI` 齿轮/链接菜单放进宿主页;完整 factory、`/admin` 前缀、headless 与自有模板示例见[新服务接入](docs/service-onboarding.md)。这不是跨服务 SSO。
63
68
 
64
69
  需要应用内 owner/admin/user、登录页、本人资料和用户管理时,新消费者显式采用 `ChatLogin>=0.2.0,<0.3.0`,并使用 `ManagedUsers` 与 `create_managed_auth`。第一个 owner 必须由操作员执行 `chatlogin users bootstrap USERNAME --instance NAME --password-env KEY` 创建;KEY 是环境变量名,绝不把密码放进 argv。它只允许空实例首次初始化,没有迁移、`--force` 或默认生产凭据。见[托管用户指南](docs/managed-users.md)。
65
70
 
@@ -1,11 +1,14 @@
1
1
  # Capability Map
2
2
 
3
+ ChatLogin 0.2.1 adds truthful `GET {prefix}/api` discovery and `AccountMenuUI` role-aware host navigation; headless does not advertise pages. See [New Service Onboarding](service-onboarding.en.md).
4
+
3
5
  ## Implemented Capabilities
4
6
 
5
7
  | Capability | Status | Boundary |
6
8
  | --- | --- | --- |
7
9
  | Packaged demo | Implemented (`demo` extra) | `chatlogin serve`, four backend experiences, a template playground, and copyable integration examples; no production data |
8
10
  | Managed-users preset | `0.2.0` | `ManagedUsers`, per-instance owner/admin/user, and default login/management/profile UI/API; explicit adoption only, with no old-store migration |
11
+ | npm frontend reuse | Source package `@chatarch/chatlogin` 0.1.0 | Framework-neutral TypeScript client and optional React login/account menu; shared protocol/CSS, Python authentication authority; see [Frontend Integration](frontend.en.md); registry release is separate |
9
12
  | ChatVoice legacy managed facade | `0.2.0` | Additive initialization over existing `accounts` / `auth_sessions`, one-time owner adoption, metadata-aware account matching, and managed-users CRUD; explicit consumer adoption required |
10
13
  | Identity and authorization | Implemented | `Principal`, `Role`, 401/403, `require_role`, and `require_owner`; admin does not bypass ownership |
11
14
  | Credential backends | Implemented | `PasswordBackend` supports one or more explicit accounts; `CallbackBackend` integrates host user stores; `AsyncCallbackBackend` awaits async upstream verification |
@@ -6,6 +6,8 @@
6
6
  | --- | --- | --- |
7
7
  | 包内演示站 | 已实现(`demo` extra) | `chatlogin serve`、四类真实后端体验、模板游乐场与可复制接入示例;不连接生产数据 |
8
8
  | 托管用户预设 | `0.2.0` | `ManagedUsers`、每实例 owner/admin/user、默认登录/管理/本人资料 UI/API;需显式采用,不迁移旧账户库 |
9
+ | 新服务发现与导航 | `0.2.1` | `GET {prefix}/api` 列出真实操作与能力;`AccountMenuUI` 复用角色入口,headless 不虚报页面;见[新服务接入](service-onboarding.md) |
10
+ | npm 前端复用 | 源码包 `@chatarch/chatlogin` 0.1.0 | 无框架 TypeScript 客户端、可选 React 登录/账号菜单;共用默认页协议和 CSS,Python 仍负责认证;见[前端接入](frontend.md),registry 发布独立执行 |
9
11
  | ChatVoice legacy 托管 facade | `0.2.0` | 保留原 `accounts` / `auth_sessions` 的 additive 初始化、一次性 owner 采用、metadata-aware 账号匹配和 managed users CRUD;需消费方显式采用 |
10
12
  | 身份与授权 | 已实现 | `Principal`、`Role`、401/403、`require_role`、`require_owner`;admin 不自动绕过 owner |
11
13
  | 认证后端 | 已实现 | `PasswordBackend` 支持一个或多个显式账号;`CallbackBackend` 接入宿主用户库;`AsyncCallbackBackend` await 异步上游校验 |
@@ -0,0 +1,96 @@
1
+ # TypeScript and React integration
2
+
3
+ `@chatarch/chatlogin` lets application-owned JavaScript/TypeScript frontends reuse ChatLogin's HTTP contract and visual resources. The Python package remains responsible for passwords, accounts, sessions, and server-side authorization. The npm package supports discovery schema 1 from Python provider 0.2.1 onward; npm and Python versions are maintained independently.
4
+
5
+ The current source package is 0.1.0. Registry publishing is a separate release step; this source change does not publish it automatically. Before release, use the package's `npm run build` and `npm pack` to verify a local tarball.
6
+
7
+ ## Framework-neutral client
8
+
9
+ Before registry publication, follow the [package README](https://github.com/ChatArch/ChatLogin/tree/main/packages/chatlogin) to build and install a local `.tgz`. After publication, use the installation command below. Create the client in a browser entry point:
10
+
11
+ ```bash
12
+ npm install @chatarch/chatlogin
13
+ ```
14
+
15
+ ```typescript
16
+ import { createChatLoginClient } from '@chatarch/chatlogin';
17
+
18
+ const client = createChatLoginClient({ basePath: '/auth' });
19
+ const manifest = await client.discover();
20
+ const session = await client.session();
21
+
22
+ const response = await client.request('/api/preferences', {
23
+ method: 'PATCH',
24
+ headers: { 'Content-Type': 'application/json' },
25
+ body: JSON.stringify({ theme: 'dark' }),
26
+ });
27
+ if (!response.ok) {
28
+ // Handle authorization, session changes, and business errors in the host.
29
+ // Do not automatically replay writes.
30
+ }
31
+ ```
32
+
33
+ | Method | Behavior |
34
+ | --- | --- |
35
+ | `discover(options?)` | Reads `{basePath}/api` and validates the schema, same-origin paths, and declared capabilities. |
36
+ | `session(options?)` | Reads the real session, including its current CSRF token, without caching it on the client object. |
37
+ | `login({ username, password, next? }, options?)` | Queries the session first and supplies CSRF when needed; the host supplies the password temporarily from its input. |
38
+ | `logout(options?)` | Queries the session and requests CSRF-protected revocation; succeeds only after confirming an anonymous session or successful revocation. |
39
+ | `request(path, init?)` | Sends a same-origin business request; unsafe methods obtain fresh session CSRF. Returns a native `Response`. |
40
+
41
+ Authentication methods distinguish HTTP, protocol, and network errors. `ChatLoginHTTPError.status` supports handling 401, 403, or 429. The host checks business `request()` response status; writes are never retried automatically. Operations accept cancellation signals and use a bounded timeout.
42
+
43
+ Login and logout mutations on one client instance run in order; adjacent logout calls may share work. This prevents an in-flight login from silently establishing a session after a completed logout. Other tabs and client instances can still change the Cookie. Hosts must refresh their session view rather than treating local state as durable authorization.
44
+
45
+ ## Optional React components
46
+
47
+ The base entry point does not import React. Install a compatible React version separately and import components from the dedicated subpath:
48
+
49
+ ```tsx
50
+ import { createChatLoginClient } from '@chatarch/chatlogin';
51
+ import { LoginForm, AccountMenu } from '@chatarch/chatlogin/react';
52
+ import '@chatarch/chatlogin/styles/login.css';
53
+ import '@chatarch/chatlogin/styles/account-menu.css';
54
+
55
+ // This example runs in a browser entry point.
56
+ const client = createChatLoginClient({ basePath: '/auth' });
57
+
58
+ export function SignIn() {
59
+ return <LoginForm client={client} title="Project sign-in" language="en" next="/" />;
60
+ }
61
+
62
+ export function Navigation() {
63
+ return <AccountMenu client={client} language="en" mode="gear"
64
+ onLogout={() => window.location.assign('/auth/')} />;
65
+ }
66
+ ```
67
+
68
+ `LoginForm` supports branding, Chinese/English copy, palettes, layouts, and appearance settings. Passwords stay in uncontrolled inputs and request memory, are cleared on submission, and never enter React state. Its success callback receives only the principal and safe local `next`. `AccountMenu` provides loading, retry, identity, role-aware links, and real logout. Change `refreshKey` after host-initiated login or account changes to refresh it.
69
+
70
+ Fixed-account backends declare `managed_users=false` and `profile=false`. Menus show only declared capabilities appropriate for the current principal. Managed-user profile and administration links also depend on returned roles and pages. Headless providers do not invent missing page links. Navigation visibility never replaces server-side authorization or business-resource ownership checks.
71
+
72
+ ## Same-origin security
73
+
74
+ Requests use same-origin Cookies, reject redirects, and disable caching. The current browser origin is authoritative; configuration cannot switch to another site. Discovery paths, page links, and business targets are validated before sending Cookie or CSRF material. Explicit `origin` and injectable `fetch` mainly support non-browser tests, not cross-site login.
75
+
76
+ Do not persist passwords, session tokens, or CSRF in localStorage, sessionStorage, URLs, or logs. CSRF returned by `session()` and low-level login results is temporary request material. Use `publicSession()` to remove it before passing session information to a display layer.
77
+
78
+ The Python service continues enforcing Host, Origin, CSRF, Cookie settings, and account permissions. `safeNext()` permits conservative local navigation; the server remains the final validator. After expiration, logout elsewhere, or changed CSRF, query the session again and let the host choose recovery. Never automatically replay a write whose outcome is unknown.
79
+
80
+ ## Shared contract and visual maintenance
81
+
82
+ TypeScript sources live under `packages/chatlogin/src/`. The build generates Python's `web/assets/client.js` and `ui.js` from `client.ts` and shared `ui.ts`. The default Python login page imports these modules, so React and the default page share the client and copy rules rather than maintaining separate login implementations.
83
+
84
+ Python's `src/chatlogin/web/assets/` owns CSS. The build copies it into npm `styles/`; keep class names, theme variables, and visual options aligned. Selectors target components or an explicitly opted-in standalone page, without resetting an embedding application's body.
85
+
86
+ When changing contracts or styles, update tests, documentation, and generated files together. Run package-local `npm run build`, `npm run check:shared`, client/React tests, and real Python ASGI contract checks. Python distributions include generated modules and need no Node.js at service startup. npm distributions contain compiled ESM, declarations, and CSS; base consumers do not need React.
87
+
88
+ The ASGI contract tool uses TestClient. Its Python test environment needs `httpx>=0.27,<1.0` alongside `ChatLogin[web]` (`[dev]` already includes it). HTTPX is a test transport, not an added production `web` dependency.
89
+
90
+ ## Why Headlamp still uses an authentication proxy
91
+
92
+ Headlamp supports HTTP authentication proxies. Python ChatLogin can supply same-origin login and session checks while a controlled proxy passes verified identity to Go Headlamp. Authentication and application components do not need the same implementation language. The deployment still owns backend binding, identity-header replacement, and Kubernetes ServiceAccount permissions.
93
+
94
+ The npm package serves application-owned frontends. It does not authorize third-party server requests or establish a centralized identity service, cross-site Cookies, or SSO. Integrating it does not require a Headlamp frontend fork or a Node.js authentication backend.
95
+
96
+ See [service onboarding](service-onboarding.en.md), [integration and security](integration.en.md), and [managed users](managed-users.en.md).
@@ -0,0 +1,96 @@
1
+ # TypeScript 与 React 前端接入
2
+
3
+ `@chatarch/chatlogin` 让自有 JavaScript/TypeScript 前端复用 ChatLogin 的 HTTP 契约和视觉资源。Python 包继续负责密码校验、账号、会话及服务端权限检查;npm 包不增加认证后端。它兼容 Python provider 0.2.1 起的发现 schema 1,npm 与 Python 分别维护版本。
4
+
5
+ 当前源码包为 0.1.0;registry 发布是独立流程,此源码变更不自动发布。正式发布前可先用包内 `npm run build`、`npm pack` 生成本地 tarball 进行接入验证。
6
+
7
+ ## 无框架客户端
8
+
9
+ 发布前可按[包 README](https://github.com/ChatArch/ChatLogin/tree/main/packages/chatlogin)生成并安装本地 `.tgz`;正式发布后使用下面的安装命令。在浏览器入口创建客户端:
10
+
11
+ ```bash
12
+ npm install @chatarch/chatlogin
13
+ ```
14
+
15
+ ```typescript
16
+ import { createChatLoginClient } from '@chatarch/chatlogin';
17
+
18
+ const client = createChatLoginClient({ basePath: '/auth' });
19
+ const manifest = await client.discover();
20
+ const session = await client.session();
21
+
22
+ // 业务接口继续由服务端验证身份、CSRF 和资源归属。
23
+ const response = await client.request('/api/preferences', {
24
+ method: 'PATCH',
25
+ headers: { 'Content-Type': 'application/json' },
26
+ body: JSON.stringify({ theme: 'dark' }),
27
+ });
28
+ if (!response.ok) {
29
+ // 宿主处理权限、会话变化和业务错误;不要自动重放写请求。
30
+ }
31
+ ```
32
+
33
+ | 方法 | 行为 |
34
+ | --- | --- |
35
+ | `discover(options?)` | 读取 `{basePath}/api`,验证 schema、同源路径和能力声明。 |
36
+ | `session(options?)` | 查询真实会话,返回身份及本次 CSRF token;不在客户端对象中缓存。 |
37
+ | `login({ username, password, next? }, options?)` | 先查会话,必要时附当前 CSRF,再发送登录请求;调用方从输入框临时提供口令。 |
38
+ | `logout(options?)` | 查询会话并用 CSRF 请求撤销;确认未登录或撤销成功后才返回成功。 |
39
+ | `request(path, init?)` | 发送同源业务请求;写方法先查询新会话并附 CSRF,返回原生 `Response`。 |
40
+
41
+ 认证方法区分 HTTP、协议与网络错误;`ChatLoginHTTPError.status` 可用于呈现 401、403 或 429。业务 `request()` 的响应状态由宿主检查;不会自动重试写入。方法支持取消信号,客户端也设置有界超时。
42
+
43
+ 同一客户端实例的登录与退出按顺序执行,相邻退出可以合并,避免“退出成功后在途登录又建立会话”。跨标签页或其他客户端实例仍可能改变 Cookie;宿主应重新查询会话并更新界面,不能把本地状态当成持续有效的授权。
44
+
45
+ ## 可选 React 组件
46
+
47
+ 基础入口不导入 React。React 使用者另行安装兼容版本,并通过独立子路径导入组件:
48
+
49
+ ```tsx
50
+ import { createChatLoginClient } from '@chatarch/chatlogin';
51
+ import { LoginForm, AccountMenu } from '@chatarch/chatlogin/react';
52
+ import '@chatarch/chatlogin/styles/login.css';
53
+ import '@chatarch/chatlogin/styles/account-menu.css';
54
+
55
+ // 本示例在浏览器入口运行。
56
+ const client = createChatLoginClient({ basePath: '/auth' });
57
+
58
+ export function SignIn() {
59
+ return <LoginForm client={client} title="项目登录" next="/" />;
60
+ }
61
+
62
+ export function Navigation() {
63
+ return <AccountMenu client={client} mode="gear"
64
+ onLogout={() => window.location.assign('/auth/')} />;
65
+ }
66
+ ```
67
+
68
+ `LoginForm` 支持标题、中英文文案、调色板、布局与明暗外观。密码保留在非受控输入及本次请求内存中,提交后清空,不进入 React 状态;成功回调只收到用户与安全的本地 `next`。`AccountMenu` 提供加载、错误重试、身份、角色感知导航与真实退出。宿主主动登录或更改账号后,可改变 `refreshKey` 触发菜单重新查询。
69
+
70
+ 固定账号后端会声明 `managed_users=false`、`profile=false`;菜单只呈现已声明且适合当前身份的能力。托管用户的资料与用户管理链接还取决于服务端返回的角色和页面。Headless 服务没有声明页面时,不会凭空生成页面入口。隐藏菜单不替代服务端权限与业务资源归属检查。
71
+
72
+ ## 同源与安全约束
73
+
74
+ 请求固定使用同源 Cookie、禁止重定向并禁用缓存。浏览器当前 origin 是信任边界,配置不能改成另一个站点;发现响应、页面链接和业务目标在发送 Cookie/CSRF 前验证。`origin` 与可注入 `fetch` 主要用于非浏览器测试,不是跨站登录配置。
75
+
76
+ 前端不持久化密码、会话 token 或 CSRF;不把 Cookie 复制到 localStorage、sessionStorage 或 URL。`session()` 和底层登录结果中的 CSRF 是短暂请求材料,宿主也不应记录或持久化它。`publicSession()` 可去除 CSRF 后再交给展示层。
77
+
78
+ Python 服务继续强制 Host、Origin、CSRF、Cookie 属性及账号权限。`safeNext()` 只允许保守的本地跳转,Python 服务仍是最终校验方。账号过期、其他页面退出或 CSRF 变化后,重新查询会话并由宿主决定恢复流程;不得自动重放结果未知的业务写入。
79
+
80
+ ## 协议和视觉资源共同维护
81
+
82
+ TypeScript 源码位于 `packages/chatlogin/src/`。构建将 `client.ts` 与共享 `ui.ts` 生成到 Python 的 `web/assets/client.js`、`ui.js`;默认 Python 登录页直接使用这些模块。React 组件和默认页因此共享 HTTP 客户端及文案规则,不各自维护一套登录请求实现。
83
+
84
+ CSS 以 Python `src/chatlogin/web/assets/` 为单源,构建复制到 npm 的 `styles/`。保持相同的类名、主题变量与视觉选项;CSS 仅作用于组件或显式选择加入的独立页面,不重置嵌入应用的 body。
85
+
86
+ 修改协议或样式时,同步契约测试、文档和生成产物。使用包内 `npm run build` 生成、`npm run check:shared` 检查漂移,再运行客户端、React 与真实 Python ASGI 契约检查。Python 安装包携带已生成模块,服务启动无需 Node.js;npm 分发携带编译后的 ESM、类型和 CSS,基础消费者无需 React。
87
+
88
+ ASGI 契约工具使用 TestClient,测试环境除 `ChatLogin[web]` 外须安装 `httpx>=0.27,<1.0`(开发用 `[dev]` 已包含)。它是测试传输依赖,不加入生产 `web` extra。
89
+
90
+ ## Headlamp 为什么继续采用认证代理
91
+
92
+ Headlamp 支持 HTTP 认证代理。Python ChatLogin 可以提供同源登录页与会话校验,由受控代理向 Go Headlamp 传入已验证身份;两端不需要使用相同语言。后端监听、身份头覆盖和 Kubernetes ServiceAccount 权限仍由部署方管理。
93
+
94
+ npm 包解决自有前端的复用问题,不会替第三方应用验证服务端请求,也不自动建立集中式身份服务、跨站共享 Cookie 或 SSO。无需为了安装 npm 包而修改 Headlamp 前端或重写 Node.js 认证服务。
95
+
96
+ 继续阅读:[新服务接入](service-onboarding.md)、[接入与安全边界](integration.md)、[托管用户](managed-users.md)。
@@ -1,5 +1,7 @@
1
1
  # ChatLogin Documentation
2
2
 
3
+ **0.2.1 new-service path:** [Complete factory, account discovery, and gear/links navigation](service-onboarding.en.md).
4
+
3
5
  ChatLogin makes the backend security contract for website login reusable in Python while leaving presentation under host control. Use the packaged page, override templates/CSS, or keep an existing HTML/vanilla-JS frontend and use the headless JSON API.
4
6
 
5
7
  Site entry: <https://arch.gh.wzhecnu.cn/ChatLogin/en/>
@@ -1,5 +1,7 @@
1
1
  # ChatLogin 文档
2
2
 
3
+ **0.2.1 新服务接入:**[查看完整 factory、账号发现和齿轮/链接菜单](service-onboarding.md)。
4
+
3
5
  ChatLogin 把网站登录中的**后端安全契约**做成可复用 Python 能力,同时把前端外观留给宿主网站:可以用包内默认登录页,也可以只覆盖模板/CSS,还可以完全保留宿主原生 HTML/JS,以 headless 方式调用 JSON 接口。
4
6
 
5
7
  站点入口:<https://arch.gh.wzhecnu.cn/ChatLogin/>
@@ -1,5 +1,7 @@
1
1
  # Integration and Security Boundaries
2
2
 
3
+ For the 0.2.1 read-only `GET {prefix}/api`, role-aware navigation, and composable menu, see [New Service Onboarding](service-onboarding.en.md). Discovery is not a session endpoint; retain the existing `GET /session` and CSRF/Origin contract.
4
+
3
5
  Start with the [complete quick integration](quickstart.md). To explore the components first, install `ChatLogin[demo]` and run `chatlogin serve`; see [Demo](demo.md).
4
6
 
5
7
  ## Choose an Integration Level
@@ -80,6 +82,8 @@ The generic HTTP adapter keeps its existing JSON fields, Origin/Host, cookie, CS
80
82
 
81
83
  Without FastAPI, install `ChatLogin[ui]` and call `LoginUI.render()`. That mode only renders templates; secure HTTP behavior remains the host's responsibility.
82
84
 
85
+ Standard-library or custom HTTP hosts adopting the Python 0.2.2 template must also serve `login.css`, `login.js`, `client.js`, and `ui.js` under the same `assets_path` (plus `account-menu.css` when used), with JavaScript MIME types. `login.js` is now an ES module: a whole-page renderer must use `<script type="module" src="…/login.js"></script>` and expand any CSS/old-script-only asset allowlist. FastAPIAuth already registers these assets; no Node runtime is needed. The npm client's Python 0.2.1/schema-v1 JSON compatibility floor is separate from deployment of the new Python template assets. Older templates or host-owned headless frontends need not change just to use the npm client.
86
+
83
87
  ## Browser HTTP Contract {#browser-contract}
84
88
 
85
89
  The default prefix is `/auth`; it can be explicitly configured as `/api/auth` or another fixed local prefix.
@@ -1,5 +1,7 @@
1
1
  # 接入与安全边界
2
2
 
3
+ 0.2.1 的只读发现入口 `GET {prefix}/api`、角色感知导航和可组合菜单见[新服务接入](service-onboarding.md)。发现不是当前会话 API,仍使用现有 `GET /session` 与 CSRF/Origin 契约。
4
+
3
5
  先按 [完整快速接入](quickstart.md) 跑通一个应用;只想体验组件时安装 `ChatLogin[demo]` 并运行 `chatlogin serve`,参见 [演示站](demo.md)。
4
6
 
5
7
  ## 选择接入层级
@@ -79,6 +81,8 @@ app.include_router(web.router)
79
81
 
80
82
  如果不使用 FastAPI,只安装 `ChatLogin[ui]` 并调用 `LoginUI.render()`;此模式只负责模板渲染,安全 HTTP 行为仍由宿主实现。
81
83
 
84
+ 采用 Python 0.2.2 模板的标准库或自定义 HTTP 宿主,还须在同一 `assets_path` 下提供 `login.css`、`login.js`、`client.js`、`ui.js`(以及需要时的 `account-menu.css`),其中 JavaScript 使用正确的 MIME。`login.js` 现在是 ES module;自有整页 renderer 引用它时须使用 `<script type="module" src="…/login.js"></script>`,不能保留仅允许 CSS/旧脚本的静态资源白名单。FastAPIAuth 已自动注册这些资源,无需 Node 运行时。npm 对 Python 0.2.1/schema v1 的 JSON 兼容底线,与这次新 Python 模板资源的部署要求是两件事;使用旧模板或自有 headless 前端无需为 npm 客户端更换原页面。
85
+
82
86
  ## 浏览器 HTTP 契约 {#browser-contract}
83
87
 
84
88
  默认前缀是 `/auth`,可显式改为 `/api/auth` 等固定本地前缀。
@@ -67,6 +67,8 @@ This is an explicit application-account preset; it does not migrate fixed-accoun
67
67
 
68
68
  ## Embeddable Managed-user Plugin
69
69
 
70
+ 0.2.1: `FastAPIAuth` and `ManagedAuth` expose `api_discovery(request)`, `navigation_from_request(request)`, and `render_account_menu(request, ui=None)`; optional `chatlogin.account_ui.AccountMenuUI(mode="gear" | "links", template_dirs=None, template_name=..., renderer=None)` renders the fragment. Discover HTTP operations through `GET {prefix}/api`; see [New Service Onboarding](service-onboarding.en.md).
71
+
70
72
  `create_managed_auth(..., pages=True)` mounts default pages and APIs; `pages=False` mounts APIs only and preserves the host frontend. See [plugin integration](managed-users.md#plugin).
71
73
 
72
74
  ## Built-in Optional ChatVoice Backend
@@ -125,6 +127,9 @@ When `LoginUI` is provided, these routes are also registered:
125
127
  GET {prefix}/ # packaged or host-overridden login page
126
128
  GET {prefix}/assets/login.css
127
129
  GET {prefix}/assets/login.js
130
+ GET {prefix}/assets/client.js # compiled TypeScript client shared by the default page
131
+ GET {prefix}/assets/ui.js # shared copy and visual options
132
+ GET {prefix}/assets/account-menu.css
128
133
  ```
129
134
 
130
135
  Without `LoginUI`, no page or asset route is registered. This is the headless mode for hosts that keep their own HTML and JavaScript.
@@ -67,6 +67,8 @@ chatlogin.managed_web
67
67
 
68
68
  ## 可内嵌托管用户插件
69
69
 
70
+ 0.2.1:`FastAPIAuth` 与 `ManagedAuth` 增加 `api_discovery(request)`、`navigation_from_request(request)`、`render_account_menu(request, ui=None)`;可选 UI 类 `chatlogin.account_ui.AccountMenuUI(mode="gear" | "links", template_dirs=None, template_name=..., renderer=None)`。HTTP 操作见 `GET {prefix}/api` 和[新服务接入](service-onboarding.md)。
71
+
70
72
  `create_managed_auth(..., pages=True)` 挂载默认页面与接口;`pages=False` 只挂载接口,保留宿主前端。详见[插件集成](managed-users.md#plugin)。
71
73
 
72
74
  ## 内建可选 ChatVoice 后端
@@ -125,6 +127,9 @@ chatlogin.fastapi
125
127
  GET {prefix}/ # 默认或宿主覆盖的登录页
126
128
  GET {prefix}/assets/login.css
127
129
  GET {prefix}/assets/login.js
130
+ GET {prefix}/assets/client.js # 默认页共用的 TypeScript 编译模块
131
+ GET {prefix}/assets/ui.js # 默认页与 React 共用文案/视觉选项
132
+ GET {prefix}/assets/account-menu.css
128
133
  ```
129
134
 
130
135
  不传 `LoginUI` 时没有页面和静态资源,适合宿主保留原前端的 headless 接入。
@@ -1,5 +1,7 @@
1
1
  # Managed Users
2
2
 
3
+ For a complete new-service factory, account menu and read-only route discovery, see [New Service Onboarding](service-onboarding.en.md). The 0.2.0 managed-user behavior remains compatible.
4
+
3
5
  This page describes the managed-users preset provided by `0.2.0`. New adopters should explicitly require `ChatLogin>=0.2.0,<0.3.0`. Existing fixed-account, callback, and ChatVoice-compatible integrations do not need to change. A legacy ChatVoice consumer's `<0.2` dependency remains unaffected unless it deliberately adopts managed users or the ChatVoice legacy-schema managed facade.
4
6
 
5
7
  ## Choose the Right Entry Point
@@ -1,5 +1,7 @@
1
1
  # 托管用户
2
2
 
3
+ 完整新服务 factory、菜单和只读路由发现见[新服务接入](service-onboarding.md);本页的 0.2.0 托管能力与行为保持兼容。
4
+
3
5
  本页说明 `0.2.0` 提供的托管用户预设。新接入方应显式声明 `ChatLogin>=0.2.0,<0.3.0`;已使用固定账号、回调或 ChatVoice 兼容后端的应用不必改变。ChatVoice 既有消费者的 `<0.2` 依赖保持不受影响,只有主动采用托管用户或 ChatVoice legacy schema 托管 facade 时才升级和接入。
4
6
 
5
7
  ## 先选择合适的入口
@@ -1,5 +1,7 @@
1
1
  # Integrate Your Own Project
2
2
 
3
+ For discovery and host-page navigation, start with [New Service Onboarding](service-onboarding.en.md): a complete factory, `/admin` prefix, gear/links menu, and headless options.
4
+
3
5
  <div class="grid cards" markdown>
4
6
 
5
7
  - **New FastAPI host**: copy the complete application below and perform a real login.
@@ -1,5 +1,7 @@
1
1
  # 快速接入自己的项目
2
2
 
3
+ 新服务需要统一账号发现与宿主页入口时,优先阅读[新服务接入](service-onboarding.md):完整 factory、`/admin` 前缀、齿轮/链接菜单及 headless 接法。
4
+
3
5
  <div class="grid cards" markdown>
4
6
 
5
7
  - **新建 FastAPI 网站**:复制下方完整应用,先完成一次真实登录。
@@ -0,0 +1,84 @@
1
+ # New-service onboarding: one account HTTP contract
2
+
3
+ ChatLogin 0.2.1 mounts an account plugin **inside each service**. One `create_managed_auth` provides login, sessions, profile and user management. Choose a gear menu, ordinary links or a host frontend without copying authentication. This is not shared-cookie SSO, a central identity service or generic CRUD for arbitrary external account providers.
4
+
5
+ ## An end-to-end new service
6
+
7
+ ```bash
8
+ python -m pip install "ChatLogin[web]==0.2.1" uvicorn
9
+ chatlogin users bootstrap operator --instance my-service --password-env MY_SERVICE_BOOTSTRAP_PASSWORD
10
+ ```
11
+
12
+ Provide the bootstrap variable through a protected process environment first. The CLI receives its name, never a password value. No production account is created automatically. Save the [complete factory](https://github.com/ChatArch/ChatLogin/blob/main/examples/managed_service.py) as `auth_app.py`, then create `app.py`:
13
+
14
+ ```python
15
+ import os
16
+ from auth_app import create_app
17
+ from chatlogin.account_ui import AccountMenuUI
18
+
19
+ app = create_app(
20
+ instance="my-service",
21
+ origin=os.environ["MY_SERVICE_ORIGIN"],
22
+ prefix="/auth", # /admin is another deployment prefix, not a permission grant
23
+ menu_ui=AccountMenuUI(mode="gear", language="en"),
24
+ allow_insecure_loopback=os.environ.get("MY_SERVICE_ALLOW_LOOPBACK") == "1",
25
+ )
26
+ ```
27
+
28
+ Production uses the actual fixed HTTPS browser origin; the host owns TLS and reverse proxying:
29
+
30
+ ```bash
31
+ MY_SERVICE_ORIGIN=https://service.example.com python -m uvicorn app:app --host 127.0.0.1 --port 8765
32
+ ```
33
+
34
+ For explicit local development only:
35
+
36
+ ```bash
37
+ MY_SERVICE_ORIGIN=http://127.0.0.1:8765 MY_SERVICE_ALLOW_LOOPBACK=1 python -m uvicorn app:app --host 127.0.0.1 --port 8765
38
+ ```
39
+
40
+ Open the homepage → Account settings → Login. Owners/admins can open management; members have their own profile. `/private` uses `auth.current_user`; `/operator` requires explicit admin/owner roles. Business-resource ownership still belongs to the host: roles do not bypass `require_owner` or ACLs.
41
+
42
+ The factory closes a store it creates during ASGI shutdown. An injected service is caller-owned and must be closed by the caller, so one host cannot destroy another host's shared in-process service. Synthetic in-memory users are only explicit test fixtures, not production defaults or an automatic migration.
43
+
44
+ ## A discoverable API root
45
+
46
+ `GET /auth/api` returns `version` (installed package), `schema_version=1` (discovery format), actual `{method, path}` `operations`, available `pages` and `login`/`managed_users`/`profile` `capabilities`. With `/admin`, the root is `/admin/api`. URLs include trusted ASGI mount metadata, not forwarded-prefix headers.
47
+
48
+ Host checking and `no-store` apply. Discovery reveals no account directory, Cookie, CSRF, credentials or state paths. It advertises provided capabilities, not actor permissions. Fixed/callback backends do not claim managed-user administration; headless mode advertises no pages. This operation directory is not a complete request/response schema or an OAuth endpoint.
49
+
50
+ | Method and relative path | JSON / result | Authorization |
51
+ | --- | --- | --- |
52
+ | `GET /api` | Discovery | Trusted Host, anonymous allowed |
53
+ | `GET /session` | authenticated, user, csrf_token | Trusted Host; anonymous gets 200 |
54
+ | `POST /login` | username, password, optional next | Same-origin; existing session needs CSRF |
55
+ | `POST /logout` | Revoke session | Current session, Origin, CSRF |
56
+ | `GET /api/users?offset=0&limit=100` | Safe metadata list, limit≤100 | Owner/admin within policy scope |
57
+ | `POST /api/users` | username, password, optional display_name/role; 201 | Owner/admin; only owner grants admin |
58
+ | `GET /api/users/{user_id}` | Safe metadata | Object-scoped owner/admin |
59
+ | `PATCH /api/users/{user_id}` | Allowed display_name/role/enabled combination | Object policy, Origin, CSRF |
60
+ | `DELETE /api/users/{user_id}` | deleted | Object policy, Origin, CSRF; never delete owner |
61
+ | `POST /api/users/{user_id}/password` | new_password | Object policy, Origin, CSRF |
62
+ | `GET /api/profile` | Own profile | Current user |
63
+ | `PATCH /api/profile` | display_name | Self, Origin, CSRF |
64
+ | `POST /api/profile/password` | current_password, new_password | Self, Origin, CSRF; invalidate old sessions |
65
+ | `POST /api/owner/transfer` | target_user_id, current_password, confirm_username | Owner reauthentication, Origin, CSRF, atomic handoff |
66
+
67
+ Use browser `credentials: 'same-origin'`, read current CSRF from `/session` and send `X-CSRF-Token` for writes. Never persist credentials, Cookie or CSRF in browser storage, URLs or logs. Common errors: 400 invalid request/Host; 401 unauthenticated; 403 policy/Origin/CSRF; 404 missing object; 409 conflict; 413 oversized body; 429 rate limit; 503 controlled capacity/service failure. The operation catalog supplements this contract and host OpenAPI; it does not replace request/response schemas.
68
+
69
+ ## Gear, links and DIY
70
+
71
+ ```python
72
+ from chatlogin.account_ui import AccountMenuUI
73
+
74
+ menu = await auth.render_account_menu(request) # Chinese-first native details
75
+ menu = await auth.render_account_menu(request, ui=AccountMenuUI(mode="links", language="en"))
76
+ menu = await auth.render_account_menu(
77
+ request, ui=AccountMenuUI(template_dirs=["templates"], template_name="account/menu.html")
78
+ )
79
+ navigation = await auth.navigation_from_request(request) # host-owned rendering
80
+ ```
81
+
82
+ Host HTML containing current identity must also set `Cache-Control: no-store`; never share-cache an account menu. Navigation resolves the actual current session. Anonymous visitors see login; members see profile; admins/owners also see management. Changes invalidate stale sessions. The native vertical gear popover needs no JavaScript initialization, has scoped CSS and inherits host typography/theme. Default rendering escapes identity/labels and validates local links; trusted custom renderers own HTML safety. Sign-out remains the existing CSRF-protected POST, not a GET link.
83
+
84
+ `pages=False` retains JSON APIs without packaged HTML/assets and produces no fake empty settings control. Host frontends use the same HTTP contract. `LoginUI`, `UserAdminUI` and `UserProfileUI` remain separately replaceable; never patch site-packages. Existing account providers retain their own lifecycle unless an explicit managed adapter exists. A unified HTTP contract is not a shared account database or cross-site SSO. See [Managed Users](managed-users.en.md) and [Integration and Security](integration.en.md).