ChatLogin 0.2.1__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.
- {chatlogin-0.2.1 → chatlogin-0.2.2}/CHANGELOG.md +8 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/DEVELOP.md +9 -0
- chatlogin-0.2.2/MANIFEST.in +13 -0
- {chatlogin-0.2.1/src/ChatLogin.egg-info → chatlogin-0.2.2}/PKG-INFO +4 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/README.en.md +3 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/README.md +3 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/capability-map.en.md +1 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/capability-map.md +1 -0
- chatlogin-0.2.2/docs/frontend.en.md +96 -0
- chatlogin-0.2.2/docs/frontend.md +96 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/integration.en.md +2 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/integration.md +2 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/interface-tree.en.md +3 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/interface-tree.md +3 -0
- chatlogin-0.2.2/examples/frontend/README.md +7 -0
- chatlogin-0.2.2/examples/frontend/react.tsx +16 -0
- chatlogin-0.2.2/examples/frontend/vanilla.ts +26 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/mkdocs.yml +2 -0
- chatlogin-0.2.2/packages/chatlogin/LICENSE +21 -0
- chatlogin-0.2.2/packages/chatlogin/README.md +85 -0
- chatlogin-0.2.2/packages/chatlogin/package-lock.json +124 -0
- chatlogin-0.2.2/packages/chatlogin/package.json +39 -0
- chatlogin-0.2.2/packages/chatlogin/scripts/build.mjs +30 -0
- chatlogin-0.2.2/packages/chatlogin/scripts/http_contract.py +107 -0
- chatlogin-0.2.2/packages/chatlogin/scripts/pack-check.mjs +53 -0
- chatlogin-0.2.2/packages/chatlogin/src/client.ts +281 -0
- chatlogin-0.2.2/packages/chatlogin/src/index.ts +2 -0
- chatlogin-0.2.2/packages/chatlogin/src/react.tsx +144 -0
- chatlogin-0.2.2/packages/chatlogin/src/ui.ts +33 -0
- {chatlogin-0.2.1/src/chatlogin/web/assets → chatlogin-0.2.2/packages/chatlogin/styles}/account-menu.css +3 -0
- chatlogin-0.2.2/packages/chatlogin/tests/client.test.mjs +204 -0
- chatlogin-0.2.2/packages/chatlogin/tests/default-page.test.mjs +77 -0
- chatlogin-0.2.2/packages/chatlogin/tests/fixtures/http-contract.json +365 -0
- chatlogin-0.2.2/packages/chatlogin/tests/react.test.mjs +107 -0
- chatlogin-0.2.2/packages/chatlogin/tests/tsconfig.json +5 -0
- chatlogin-0.2.2/packages/chatlogin/tests/types.test.tsx +21 -0
- chatlogin-0.2.2/packages/chatlogin/tsconfig.json +10 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2/src/ChatLogin.egg-info}/PKG-INFO +4 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/ChatLogin.egg-info/SOURCES.txt +27 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/__init__.py +1 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo.py +1 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/fastapi.py +6 -1
- chatlogin-0.2.2/src/chatlogin/web/assets/account-menu.css +19 -0
- chatlogin-0.2.2/src/chatlogin/web/assets/client.js +282 -0
- chatlogin-0.2.2/src/chatlogin/web/assets/login.css +67 -0
- chatlogin-0.2.2/src/chatlogin/web/assets/login.js +36 -0
- chatlogin-0.2.2/src/chatlogin/web/assets/ui.js +35 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/login.html +1 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_demo_release_contract.py +16 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_live_login_service.py +2 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_packaging_imports.py +2 -2
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_service_onboarding.py +1 -1
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_ui_contract.py +4 -2
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_web.py +6 -2
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_version.py +1 -1
- chatlogin-0.2.1/MANIFEST.in +0 -7
- chatlogin-0.2.1/src/chatlogin/web/assets/login.js +0 -67
- {chatlogin-0.2.1 → chatlogin-0.2.2}/LICENSE +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/chatvoice-managed.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/chatvoice-managed.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/cli-tree.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/cli-tree.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/demo.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/demo.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/index.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/index.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/managed-users.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/managed-users.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/quickstart.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/quickstart.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/service-onboarding.en.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/docs/service-onboarding.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/examples/demo_fastapi.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/examples/managed_service.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/examples/quickstart_fastapi.py +0 -0
- {chatlogin-0.2.1/src/chatlogin/web/assets → chatlogin-0.2.2/packages/chatlogin/styles}/login.css +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/pyproject.toml +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/setup.cfg +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/ChatLogin.egg-info/dependency_links.txt +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/ChatLogin.egg-info/entry_points.txt +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/ChatLogin.egg-info/requires.txt +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/ChatLogin.egg-info/top_level.txt +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/account_ui.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/backends/__init__.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/backends/chatvoice.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/backends/chatvoice_managed.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/cli.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/config.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/credentials.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/__init__.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo-login.css +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo-login.js +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo.css +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/assets/demo.js +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/headless.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/home.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/managed.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/templates.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/demo_site/templates/workspace.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/identity.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/managed.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/managed_demo.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/managed_web.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/paths.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/private_sqlite.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/security.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/sessions.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/sqlite.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/ui.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/user_ui.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/__init__.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/assets/users.css +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/assets/users.js +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/account-menu.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/profile.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/src/chatlogin/web/templates/chatlogin/users.html +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/cli-tests/README.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/README.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_async_credentials.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_chatvoice_backend.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_chatvoice_managed_backend.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_core.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_core_guards.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_demo_multiuser.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_demo_site.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_demo_ux.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_http_guards.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_concurrency.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_demo.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_form_safety.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_integration.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_journal_race.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_plugin.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_read_snapshot.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_sessions.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_ui.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_users.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_managed_web.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_onboarding_acceptance.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_origin_mount.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_packaging_demo.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_scaffold_contract.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_session_purge.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_sqlite_security.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/code-tests/test_storage_platform.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/conftest.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/mock-cli-tests/README.md +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_cli.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_docs_deployment.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_managed_cli.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_managed_docs.py +0 -0
- {chatlogin-0.2.1 → chatlogin-0.2.2}/tests/test_paths_cli.py +0 -0
|
@@ -1,5 +1,13 @@
|
|
|
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
|
+
|
|
3
11
|
## 0.2.1 — 2026-10-14
|
|
4
12
|
|
|
5
13
|
- 新增 Host 校验、no-store 的 `GET {prefix}/api`,按真实路由和可信 ASGI mount 发现操作、页面和能力;headless 不声明页面。
|
|
@@ -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.
|
|
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
|
## 安装
|
|
@@ -107,6 +108,8 @@ chatlogin serve --host 127.0.0.1 --port 8765 --origin https://login.example.com
|
|
|
107
108
|
|
|
108
109
|
## 托管用户(0.2.1)
|
|
109
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
|
+
|
|
110
113
|
新服务可通过 `GET {prefix}/api` 发现真实注册路由,并把 `AccountMenuUI` 齿轮/链接菜单放进宿主页;完整 factory、`/admin` 前缀、headless 与自有模板示例见[新服务接入](docs/service-onboarding.md)。这不是跨服务 SSO。
|
|
111
114
|
|
|
112
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)。
|
|
@@ -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
|
|
@@ -61,6 +62,8 @@ The core package does not require adopting the packaged page. An existing static
|
|
|
61
62
|
|
|
62
63
|
## Managed Users (0.2.1)
|
|
63
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
|
+
|
|
64
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.
|
|
65
68
|
|
|
66
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).
|
|
@@ -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
|
## 安装
|
|
@@ -61,6 +62,8 @@ chatlogin serve --host 127.0.0.1 --port 8765 --origin https://login.example.com
|
|
|
61
62
|
|
|
62
63
|
## 托管用户(0.2.1)
|
|
63
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
|
+
|
|
64
67
|
新服务可通过 `GET {prefix}/api` 发现真实注册路由,并把 `AccountMenuUI` 齿轮/链接菜单放进宿主页;完整 factory、`/admin` 前缀、headless 与自有模板示例见[新服务接入](docs/service-onboarding.md)。这不是跨服务 SSO。
|
|
65
68
|
|
|
66
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)。
|
|
@@ -8,6 +8,7 @@ ChatLogin 0.2.1 adds truthful `GET {prefix}/api` discovery and `AccountMenuUI` r
|
|
|
8
8
|
| --- | --- | --- |
|
|
9
9
|
| Packaged demo | Implemented (`demo` extra) | `chatlogin serve`, four backend experiences, a template playground, and copyable integration examples; no production data |
|
|
10
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 |
|
|
11
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 |
|
|
12
13
|
| Identity and authorization | Implemented | `Principal`, `Role`, 401/403, `require_role`, and `require_owner`; admin does not bypass ownership |
|
|
13
14
|
| Credential backends | Implemented | `PasswordBackend` supports one or more explicit accounts; `CallbackBackend` integrates host user stores; `AsyncCallbackBackend` awaits async upstream verification |
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
| 包内演示站 | 已实现(`demo` extra) | `chatlogin serve`、四类真实后端体验、模板游乐场与可复制接入示例;不连接生产数据 |
|
|
8
8
|
| 托管用户预设 | `0.2.0` | `ManagedUsers`、每实例 owner/admin/user、默认登录/管理/本人资料 UI/API;需显式采用,不迁移旧账户库 |
|
|
9
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 发布独立执行 |
|
|
10
11
|
| ChatVoice legacy 托管 facade | `0.2.0` | 保留原 `accounts` / `auth_sessions` 的 additive 初始化、一次性 owner 采用、metadata-aware 账号匹配和 managed users CRUD;需消费方显式采用 |
|
|
11
12
|
| 身份与授权 | 已实现 | `Principal`、`Role`、401/403、`require_role`、`require_owner`;admin 不自动绕过 owner |
|
|
12
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)。
|
|
@@ -82,6 +82,8 @@ The generic HTTP adapter keeps its existing JSON fields, Origin/Host, cookie, CS
|
|
|
82
82
|
|
|
83
83
|
Without FastAPI, install `ChatLogin[ui]` and call `LoginUI.render()`. That mode only renders templates; secure HTTP behavior remains the host's responsibility.
|
|
84
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
|
+
|
|
85
87
|
## Browser HTTP Contract {#browser-contract}
|
|
86
88
|
|
|
87
89
|
The default prefix is `/auth`; it can be explicitly configured as `/api/auth` or another fixed local prefix.
|
|
@@ -81,6 +81,8 @@ app.include_router(web.router)
|
|
|
81
81
|
|
|
82
82
|
如果不使用 FastAPI,只安装 `ChatLogin[ui]` 并调用 `LoginUI.render()`;此模式只负责模板渲染,安全 HTTP 行为仍由宿主实现。
|
|
83
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
|
+
|
|
84
86
|
## 浏览器 HTTP 契约 {#browser-contract}
|
|
85
87
|
|
|
86
88
|
默认前缀是 `/auth`,可显式改为 `/api/auth` 等固定本地前缀。
|
|
@@ -127,6 +127,9 @@ When `LoginUI` is provided, these routes are also registered:
|
|
|
127
127
|
GET {prefix}/ # packaged or host-overridden login page
|
|
128
128
|
GET {prefix}/assets/login.css
|
|
129
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
|
|
130
133
|
```
|
|
131
134
|
|
|
132
135
|
Without `LoginUI`, no page or asset route is registered. This is the headless mode for hosts that keep their own HTML and JavaScript.
|
|
@@ -127,6 +127,9 @@ chatlogin.fastapi
|
|
|
127
127
|
GET {prefix}/ # 默认或宿主覆盖的登录页
|
|
128
128
|
GET {prefix}/assets/login.css
|
|
129
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
|
|
130
133
|
```
|
|
131
134
|
|
|
132
135
|
不传 `LoginUI` 时没有页面和静态资源,适合宿主保留原前端的 headless 接入。
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Browser integrations
|
|
2
|
+
|
|
3
|
+
Both examples consume the same-origin Python routes. Mount `FastAPIAuth` for fixed/callback accounts, or `create_managed_auth` for managed users, under `/auth` as described in [new-service onboarding](../../docs/service-onboarding.en.md). Set the server's concrete public Origin and keep server-side role/resource checks. Never pass production credentials through this source tree.
|
|
4
|
+
|
|
5
|
+
Build/pack the npm package first; a consuming application can install the resulting `.tgz` until a registry release exists. `vanilla.ts` expects host-owned `#sign-in` (username/password inputs), `#sign-in-status`, and optional `#sign-out`. `react.tsx` is a client-only component and imports styles explicitly. SSR hosts must instantiate the client after hydration, not while rendering on the server.
|
|
6
|
+
|
|
7
|
+
Use one stable client instance per auth prefix. Increment `AccountMenu.refreshKey` after login/account changes or when the host observes expiry in another tab. Do not infer authorization from visible menu links. These snippets do not start servers, create accounts, store passwords/tokens, provide SSO, or install a Node authentication backend.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/** Browser client component. Instantiate after hydration in SSR hosts. */
|
|
2
|
+
import { useMemo, useState } from 'react';
|
|
3
|
+
import { createChatLoginClient } from '@chatarch/chatlogin';
|
|
4
|
+
import { AccountMenu, LoginForm } from '@chatarch/chatlogin/react';
|
|
5
|
+
import '@chatarch/chatlogin/styles/login.css';
|
|
6
|
+
import '@chatarch/chatlogin/styles/account-menu.css';
|
|
7
|
+
|
|
8
|
+
export function AccountArea() {
|
|
9
|
+
const auth = useMemo(() => createChatLoginClient({ basePath: '/auth' }), []);
|
|
10
|
+
const [revision, refresh] = useState(0);
|
|
11
|
+
return <>
|
|
12
|
+
<AccountMenu client={auth} refreshKey={revision} onLogout={() => refresh(value => value + 1)} />
|
|
13
|
+
<LoginForm client={auth} title="My application" layout="split" appearance="system"
|
|
14
|
+
onSuccess={() => refresh(value => value + 1)} />
|
|
15
|
+
</>;
|
|
16
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** Browser-only host example. Its Python auth routes remain the authority. */
|
|
2
|
+
import { createChatLoginClient, ChatLoginHTTPError } from '@chatarch/chatlogin';
|
|
3
|
+
|
|
4
|
+
const auth = createChatLoginClient({ basePath: '/auth' });
|
|
5
|
+
const form = document.querySelector<HTMLFormElement>('#sign-in');
|
|
6
|
+
const status = document.querySelector<HTMLElement>('#sign-in-status');
|
|
7
|
+
|
|
8
|
+
form?.addEventListener('submit', async event => {
|
|
9
|
+
event.preventDefault();
|
|
10
|
+
const username = form.elements.namedItem('username') as HTMLInputElement;
|
|
11
|
+
const password = form.elements.namedItem('password') as HTMLInputElement;
|
|
12
|
+
const input = { username: username.value, password: password.value, next: '/workspace' };
|
|
13
|
+
password.value = '';
|
|
14
|
+
try {
|
|
15
|
+
const result = await auth.login(input);
|
|
16
|
+
window.location.assign(result.next);
|
|
17
|
+
} catch (error) {
|
|
18
|
+
if (status) status.textContent = error instanceof ChatLoginHTTPError && error.status === 401
|
|
19
|
+
? 'Check your account and password.' : 'Sign-in did not complete. Please retry.';
|
|
20
|
+
}
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
document.querySelector('#sign-out')?.addEventListener('click', async () => {
|
|
24
|
+
await auth.logout(); // failure keeps the current page; do not claim revocation
|
|
25
|
+
window.location.assign('/auth/');
|
|
26
|
+
});
|
|
@@ -44,6 +44,7 @@ plugins:
|
|
|
44
44
|
演示站与快速开始: Demo and Quick Start
|
|
45
45
|
托管用户: Managed Users
|
|
46
46
|
新服务接入: New Service Onboarding
|
|
47
|
+
TypeScript 与 React 前端: TypeScript and React Frontends
|
|
47
48
|
ChatVoice legacy schema 集成: ChatVoice Legacy Schema Integration
|
|
48
49
|
markdown_extensions:
|
|
49
50
|
- admonition
|
|
@@ -73,6 +74,7 @@ nav:
|
|
|
73
74
|
- 接入与安全: integration.md
|
|
74
75
|
- 托管用户: managed-users.md
|
|
75
76
|
- 新服务接入: service-onboarding.md
|
|
77
|
+
- TypeScript 与 React 前端: frontend.md
|
|
76
78
|
- ChatVoice legacy schema 集成: chatvoice-managed.md
|
|
77
79
|
- 命令与接口:
|
|
78
80
|
- CLI 树: cli-tree.md
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ChatArch
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# @chatarch/chatlogin
|
|
2
|
+
|
|
3
|
+
ChatLogin 的同源浏览器客户端,以及可选 React 登录和账号菜单。Python provider 继续校验密码、管理账号和会话、检查 CSRF 与权限;此包不提供认证后端或跨站 SSO。
|
|
4
|
+
|
|
5
|
+
源码包版本 `0.1.0`,使用 Python ChatLogin `0.2.1` 引入的 HTTP schema v1。npm 与 Python 独立版本;Python 默认页面资源从 0.2.2 起共用该实现。npm 通过独立 `npm-v<version>` 标签发布;正式首发完成前可按下面的打包流程安装本地 `.tgz`。
|
|
6
|
+
|
|
7
|
+
## 基础客户端
|
|
8
|
+
|
|
9
|
+
发布后安装 `npm install @chatarch/chatlogin`。基础入口没有运行时依赖,不需要 React;仅提供 ESM,支持现代浏览器的 Fetch、Cookie、AbortController 和 TextDecoder。
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { createChatLoginClient, ChatLoginHTTPError } from '@chatarch/chatlogin';
|
|
13
|
+
|
|
14
|
+
const auth = createChatLoginClient({ basePath: '/auth' });
|
|
15
|
+
const manifest = await auth.discover(); // /auth/api; schema, real pages and capabilities
|
|
16
|
+
const session = await auth.session(); // public identity + short-lived in-memory CSRF
|
|
17
|
+
|
|
18
|
+
await auth.login({ username, password, next: '/workspace' });
|
|
19
|
+
// Browser owns the HttpOnly session cookie. Do not save passwords or CSRF.
|
|
20
|
+
const response = await auth.request('/api/preferences', {
|
|
21
|
+
method: 'PATCH', headers: { 'Content-Type': 'application/json' },
|
|
22
|
+
body: JSON.stringify({ theme: 'dark' }),
|
|
23
|
+
});
|
|
24
|
+
await auth.logout();
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`basePath` 是浏览器可见的安全绝对路径,包含 ASGI mount 前缀,例如 `/tools/admin`。不能填外部 URL。客户端总是使用 `credentials: 'same-origin'`、`mode: 'same-origin'`、`cache: 'no-store'`、`redirect: 'error'`,不手设 Origin、Cookie 或 Authorization。构造函数的 `origin`/`fetch` 是无浏览器契约测试的注入点;浏览器内 `origin` 必须与当前页面一致。
|
|
28
|
+
|
|
29
|
+
登录前读新鲜会话,已有 Cookie 时带新鲜 CSRF;退出和业务写请求也重新查询。`request()` 为 POST/PUT/PATCH/DELETE 加 CSRF,拒绝匿名写入,GET/HEAD/OPTIONS 不携带 CSRF。它返回原始业务 Response(含非 2xx),由宿主检查 `response.ok` 并解释业务错误。认证方法及会话预检查的非 2xx 抛 `ChatLoginHTTPError`,不会把服务端正文或凭据放进错误信息。403、网络失败和超时不自动重试有副作用的请求。默认每次操作 15 秒,可配置 `timeoutMs`(0–120000 之间的正数),或传入 `signal`。
|
|
30
|
+
|
|
31
|
+
同一客户端实例的登录与退出完整串行,只有相邻的并发退出合并;合并时第一个调用者拥有取消信号。其他客户端实例、浏览器标签页及服务端密码/角色变化仍需宿主重新读取会话。客户端不缓存认证状态、不操作 localStorage/sessionStorage,也不读取会话 Cookie。
|
|
32
|
+
|
|
33
|
+
## 可选 React
|
|
34
|
+
|
|
35
|
+
只有导入 `@chatarch/chatlogin/react` 才需要宿主提供 React `^18.2.0 || ^19.0.0`。样式显式引入;不会自动修改宿主 body。
|
|
36
|
+
|
|
37
|
+
```tsx
|
|
38
|
+
import { useState } from 'react';
|
|
39
|
+
import { createChatLoginClient } from '@chatarch/chatlogin';
|
|
40
|
+
import { LoginForm, AccountMenu } from '@chatarch/chatlogin/react';
|
|
41
|
+
import '@chatarch/chatlogin/styles/login.css';
|
|
42
|
+
import '@chatarch/chatlogin/styles/account-menu.css';
|
|
43
|
+
|
|
44
|
+
const auth = createChatLoginClient({ basePath: '/auth' }); // in the browser
|
|
45
|
+
|
|
46
|
+
export function AccountArea() {
|
|
47
|
+
const [revision, refresh] = useState(0);
|
|
48
|
+
return <>
|
|
49
|
+
<AccountMenu client={auth} refreshKey={revision} onLogout={() => refresh(n => n + 1)} />
|
|
50
|
+
<LoginForm client={auth} layout="split" appearance="system"
|
|
51
|
+
onSuccess={() => refresh(n => n + 1)} />
|
|
52
|
+
</>;
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`LoginForm` 支持 title/subtitle/eyebrow、三种 palette、card/split、light/dark/system、zh-CN/en,以及可信宿主的本地 guestUrl。无 `onSuccess` 时跳转到经验证的同源 `next`;提供回调则由宿主处理导航。密码不进入 React state,回调只返回 user/next,不含密码或 CSRF。
|
|
57
|
+
|
|
58
|
+
`AccountMenu` 支持 gear/links、zh-CN/en、refreshKey、onLogout/onError。状态存储只含公开身份,不保留 CSRF。固定账号显示身份与真实退出,不捏造用户管理链接;托管用户仅在能力、真实页面和角色匹配时显示资料/管理链接;headless 的 `pages={}` 不产生链接。菜单提示不是权限检查,服务端仍须检查业务数据归属。跨标签页变化由宿主触发 refreshKey;不做跨站身份同步。
|
|
59
|
+
|
|
60
|
+
## 共享维护与验证
|
|
61
|
+
|
|
62
|
+
单源方向如下,`npm run check:shared` 会在漂移时失败:
|
|
63
|
+
|
|
64
|
+
1. `src/client.ts`、`src/ui.ts` → 编译为 npm ESM 与 Python 默认页的 `client.js`、`ui.js`。
|
|
65
|
+
2. Python `src/chatlogin/web/assets/{login,account-menu}.css` → npm `styles/`;两端共用 `--cl-*`、class、主题和布局约定。
|
|
66
|
+
3. `scripts/http_contract.py` 从真实 Python ASGI 路由生成脱敏 fixtures;`--check` 验证协议与 UI tokens,Node 测试消费这些 fixtures。
|
|
67
|
+
|
|
68
|
+
Python 的已构建 wheel 包含生成的浏览器资源,生产安装不需要 Node。Jinja 与 React 保留各自的语义标记;公共 class、默认字段/主题及协议由契约测试约束。不要手工修改生成的 client/ui JavaScript 或 npm CSS 副本。
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
cd packages/chatlogin
|
|
72
|
+
npm ci --ignore-scripts
|
|
73
|
+
npm run build
|
|
74
|
+
python scripts/http_contract.py --check # Python test env: ChatLogin[web] + httpx
|
|
75
|
+
npm run check:shared
|
|
76
|
+
npm test
|
|
77
|
+
npm run typecheck
|
|
78
|
+
npm run pack:check
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`pack:check` 检查 tarball 白名单,在无 React 的干净消费者中安装并导入基础包、编译其公开类型。它不调用 publish。更多说明见仓库 [frontend.md](https://github.com/ChatArch/ChatLogin/blob/main/docs/frontend.md),接入示例见 [examples/](https://github.com/ChatArch/ChatLogin/tree/main/examples/frontend)。Headlamp 等 Go 服务仍通过 HTTP 认证代理保护;npm 包用于自有 JS/TS 界面复用,无法替代服务器密码与权限校验。
|
|
82
|
+
|
|
83
|
+
## 发布维护
|
|
84
|
+
|
|
85
|
+
Python 和 npm 分别使用 `v<python-version>` 与 `npm-v<npm-version>`,标签须指向已合并的 `main` 提交。Python 沿用 `publish.yml` 的 PyPI Trusted Publisher;npm 的 Trusted Publisher 绑定 `ChatArch/ChatLogin`、工作流 `publish-npm.yml`,在 GitHub-hosted runner 通过 OIDC/provenance 发布,不读取长期 `NPM_TOKEN`。首次 npm 项目需先按 npm 官方流程完成组织身份和首发,再配置该信任关系;workflow 文件本身不构成 registry 授权。
|