@dplugin/core 2.0.0 → 2.0.1
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.
- package/README.md +306 -214
- package/package.json +1 -9
package/README.md
CHANGED
|
@@ -1,131 +1,310 @@
|
|
|
1
1
|
# @dplugin/core
|
|
2
2
|
|
|
3
|
-
DPlugin 前端登录与请求 SDK
|
|
3
|
+
DPlugin 前端登录与请求 SDK。零运行时依赖(不用 axios / crypto-js / jsencrypt),浏览器原生
|
|
4
|
+
`fetch` + `WebCrypto`。
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
两种模式**按 origin 自动选择**,业务代码几乎不用区分:
|
|
6
7
|
|
|
7
|
-
| | 触发条件 | 凭证 |
|
|
8
|
-
|
|
9
|
-
| **cookie** |
|
|
10
|
-
| **sign** |
|
|
8
|
+
| 模式 | 触发条件 | 凭证 | 每请求形态 |
|
|
9
|
+
|---|---|---|---|
|
|
10
|
+
| **cookie** | 页面与接口**同源**(scheme + host + port 全等) | 服务端下发的 HttpOnly Cookie | 无签名参数,浏览器自动带 Cookie |
|
|
11
|
+
| **sign** | 页面与接口**跨源** | `access`(localStorage) | 一个 `dsign` 签名信封(query 参数) |
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- 续期:`500900` → `POST /c/refresh`(无参数)→ 重发
|
|
18
|
-
- 退出:`POST /api/safe/dplugin/login/logout`(无参数),服务端清 `dp_sid`/`dp_token`
|
|
19
|
-
- `isLogin()` 只是本地标记(HttpOnly 读不到),真正有效性以第一次请求为准
|
|
13
|
+
```js
|
|
14
|
+
setup({apiBase: ''}) // 同源 → cookie 模式
|
|
15
|
+
setup({apiBase: 'https://api.other.com'}) // 跨源 → sign 模式
|
|
16
|
+
setup({apiBase: '', mode: 'sign'}) // 也可以强制指定
|
|
17
|
+
```
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
- 登录:`submit`(上报 sso 公钥)→ 轮询 `POST /s/verify`(带签名)→ `code` 换 `access`(上报域公钥)
|
|
23
|
-
- 业务:每次请求带 `dsign` 信封(access/设备/时间/签名,域私钥签)
|
|
24
|
-
- 续期:`500900` → 用 sso 私钥走 `VERIFY_SID` 换 code → `TOKEN` 换新 access(**不再有 REFRESH**)
|
|
19
|
+
两条链路在服务端是同一套 sso/域会话,互不干扰。
|
|
25
20
|
|
|
26
|
-
|
|
21
|
+
---
|
|
27
22
|
|
|
28
23
|
## 安装
|
|
29
24
|
|
|
25
|
+
**npm**
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm i @dplugin/core
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**CDN(UMD,挂到 `window.DPluginCore`)**
|
|
32
|
+
|
|
33
|
+
```html
|
|
34
|
+
<script src="https://unpkg.com/@dplugin/core@2.0.0/dist/index.umd.js"></script>
|
|
35
|
+
<script>
|
|
36
|
+
const {setup, login, request, logout} = window.DPluginCore;
|
|
37
|
+
</script>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**本地源码调试**(还没发版时)
|
|
41
|
+
|
|
30
42
|
```bash
|
|
31
|
-
#
|
|
32
|
-
# ⚠️ 干净 clone 后必须先在**本目录**跑一次 npm install && npm run build:
|
|
33
|
-
# dist/ 不入库,而页面通过 exports 解析到 dist/index.mjs,缺了会报
|
|
34
|
-
# "Failed to resolve entry for package @dplugin/core"
|
|
43
|
+
# 本目录先构建一次,dist/ 不入库
|
|
35
44
|
npm install && npm run build
|
|
36
|
-
|
|
45
|
+
|
|
46
|
+
# 页面 package.json
|
|
47
|
+
"@dplugin/core": "file:../dplugin-login-umdjs-core"
|
|
37
48
|
```
|
|
38
49
|
|
|
39
|
-
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 快速上手
|
|
53
|
+
|
|
54
|
+
### 1) 入口初始化(每个应用只调一次)
|
|
40
55
|
|
|
41
56
|
```js
|
|
42
|
-
// main.js
|
|
43
|
-
import {setup
|
|
57
|
+
// main.js
|
|
58
|
+
import {setup} from '@dplugin/core';
|
|
44
59
|
|
|
45
60
|
setup({
|
|
46
|
-
apiBase: import.meta.env.VITE_API_BASE_URL, // '' = 同源
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
61
|
+
apiBase: import.meta.env.VITE_API_BASE_URL, // '' = 同源
|
|
62
|
+
loginUrl: '/login/',
|
|
63
|
+
onError: ({code, message}) => {
|
|
64
|
+
// 业务错误统一提示(登录态的 500900 不会走到这里)
|
|
65
|
+
Modal.error({title: '操作失败[' + code + ']', content: message});
|
|
66
|
+
},
|
|
50
67
|
onLogout: () => router.replace('/login')
|
|
51
68
|
});
|
|
52
69
|
```
|
|
53
70
|
|
|
71
|
+
### 2) 登录(登录页)
|
|
72
|
+
|
|
54
73
|
```js
|
|
55
|
-
|
|
74
|
+
import {login} from '@dplugin/core';
|
|
75
|
+
|
|
56
76
|
await login('/api/unsafe/dplugin/user/login/pwd/submit', {username, password});
|
|
57
77
|
location.href = '/';
|
|
58
78
|
```
|
|
59
79
|
|
|
80
|
+
`login()` 收的是**登录方式的 submit 接口**,所以手机验证码登录只是换接口和参数:
|
|
81
|
+
|
|
60
82
|
```js
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
83
|
+
await login('/api/unsafe/dplugin/user/login/phone/submit', {phone, code});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
内部流程(业务不需要管):
|
|
87
|
+
|
|
88
|
+
| 模式 | 步骤 |
|
|
89
|
+
|---|---|
|
|
90
|
+
| cookie | `submit` → 种临时 token(`dp_dvt`)→ 轮询 `/c/verify` → `/c/token` 换业务凭证 |
|
|
91
|
+
| sign | `submit`(上报 sso 公钥)→ 轮询 `/s/verify` → `/s/token` 换 access(上报域公钥) |
|
|
92
|
+
|
|
93
|
+
### 3) 业务请求
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
import {request} from '@dplugin/core';
|
|
97
|
+
|
|
98
|
+
// 返回值就是后端 data
|
|
99
|
+
const user = await request('/api/safe/dplugin/user/get');
|
|
100
|
+
await request('/api/safe/dplugin/user/update', {nickname: 'x'});
|
|
101
|
+
|
|
102
|
+
// 匿名接口:不要求登录,失效也不跳登录页
|
|
103
|
+
const setting = await request('/api/unsafe/dplugin/login/page/setting', {}, {auth: false});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
业务错误抛 `BizError`(同时触发一次 `onError`)。
|
|
107
|
+
|
|
108
|
+
### 4) 上传
|
|
109
|
+
|
|
110
|
+
```js
|
|
111
|
+
import {upload} from '@dplugin/core';
|
|
112
|
+
|
|
113
|
+
await upload('/api/safe/dplugin/storage/upload', file, {bizType: 'avatar'}, {timeout: 60000});
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 5) 退出
|
|
117
|
+
|
|
118
|
+
```js
|
|
119
|
+
import {logout} from '@dplugin/core';
|
|
120
|
+
await logout(); // 服务端会话 + 本地状态一起清
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## 判断登录态
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
import {isLogin, getState, verifyLogin} from '@dplugin/core';
|
|
129
|
+
|
|
130
|
+
isLogin(); // 同步、不发请求:「本地看起来是否已登录」
|
|
131
|
+
getState(); // {mode, loggedIn, hasAccess, sid, ds}
|
|
132
|
+
await verifyLogin();// 可选:向服务端确认一次,返回 true / false
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
两种模式下 `isLogin()` 的含义:
|
|
136
|
+
|
|
137
|
+
- **sign**:localStorage 里有 access 或 sid 就是 true(access 过期也能静默恢复)
|
|
138
|
+
- **cookie**:凭证在 HttpOnly Cookie 里,JS 读不到,只代表「上次登录过的标记」
|
|
139
|
+
|
|
140
|
+
**真正是否有效,以第一次 `request()` 的结果为准**:失效时 SDK 会自动续期一次,续不回来才抛 `AuthError`。
|
|
141
|
+
|
|
142
|
+
```js
|
|
143
|
+
// 页面加载时的典型写法
|
|
144
|
+
if (!isLogin()) {
|
|
145
|
+
router.replace('/login');
|
|
146
|
+
} else {
|
|
147
|
+
// 可选:需要准确判断时再打一次服务端
|
|
148
|
+
// if (!await verifyLogin()) router.replace('/login');
|
|
70
149
|
}
|
|
71
150
|
```
|
|
72
151
|
|
|
73
|
-
|
|
74
|
-
提示与跳转都由业务处理(登录页无需额外配置)。
|
|
152
|
+
---
|
|
75
153
|
|
|
76
|
-
##
|
|
154
|
+
## 会话失效会自动续期
|
|
77
155
|
|
|
78
|
-
|
|
156
|
+
业务请求返回 `500900` 时,SDK 自动续期一次再重发:
|
|
157
|
+
|
|
158
|
+
| 模式 | 续期 |
|
|
79
159
|
|---|---|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
| `upload(api, file, data?, options?)` | multipart 上传(签名参数在 query,文件在 body);`options.timeout` 单独放宽超时 |
|
|
83
|
-
| `login(submitApi, params)` | 完整登录流程,返回 `{loggedIn, sid, ds}` |
|
|
84
|
-
| `logout()` | 退出(access 过期会先续期再退,保证服务端会话被删) |
|
|
85
|
-
| `verifyLogin(options?)` | 页面加载时恢复登录态;`{force:true}` 强制换一次 token |
|
|
86
|
-
| `isLogin()` / `getState()` | `getState()` = `{loggedIn, hasAccess, sid, ds}`,**不暴露 access**;`isLogin()` 是本地提示(有 access 或 sid 即为 true) |
|
|
87
|
-
| `clear()` / `expire(reason?)` | 只清本地 / 清本地并跳登录页 |
|
|
88
|
-
| `auth` | 门面:`{login, logout, isLogin, getState, restore}` |
|
|
89
|
-
| `BizError` / `AuthError` / `CODE` / `isAuthError` | 错误类型与码值常量 |
|
|
90
|
-
| `store` | 登录态存储(access / sid / ds),一般不需要直接用 |
|
|
160
|
+
| cookie | `POST /api/unsafe/dplugin/login/c/refresh`(凭 Cookie,无参数) |
|
|
161
|
+
| sign | `POST /api/unsafe/dplugin/login/s/refresh?dsign=…`(`BIZ` 信封,subject = 当前 access) |
|
|
91
162
|
|
|
92
|
-
|
|
163
|
+
所以业务侧不用写任何续期逻辑:
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
try {
|
|
167
|
+
const data = await request('/api/safe/xxx');
|
|
168
|
+
} catch (e) {
|
|
169
|
+
if (isAuthError(e)) {
|
|
170
|
+
// 续期也救不回来:让用户重新登录(onLogout 已经回调过)
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 配置项(`setup`)
|
|
93
178
|
|
|
94
179
|
| 字段 | 默认 | 说明 |
|
|
95
180
|
|---|---|---|
|
|
96
|
-
| `apiBase` | `''` |
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
181
|
+
| `apiBase` | `''` | 接口前缀。`''` = 同源 |
|
|
182
|
+
| `mode` | `'auto'` | `'auto'` / `'cookie'` / `'sign'` |
|
|
183
|
+
| `loginUrl` | `'/login/'` | 仅当 `enableAuth: true` 时由 SDK 跳这里 |
|
|
184
|
+
| `enableAuth` | `false` | 默认**不**跳转:失效只清本地 + `onLogout` + 抛 `AuthError`,提示/跳转交给业务 |
|
|
99
185
|
| `timeout` | `15000` | 请求超时(毫秒) |
|
|
100
186
|
| `pollInterval` | `2000` | 登录轮询间隔(毫秒) |
|
|
101
|
-
| `pollMax` | `5` |
|
|
102
|
-
| `nativeGuard` | `'warn'` |
|
|
103
|
-
| `onError` | - | `({code, message, error})
|
|
187
|
+
| `pollMax` | `5` | 登录轮询次数,用完报「登录超时」 |
|
|
188
|
+
| `nativeGuard` | `'warn'` | 原生能力指纹检查:`warn` / `error` / `off` |
|
|
189
|
+
| `onError` | - | `({code, message, error})` 业务错误提示 |
|
|
104
190
|
| `onLogin` | - | `(state)` 登录 / 静默恢复成功 |
|
|
105
|
-
| `onLogout` | - | `(reason)`
|
|
191
|
+
| `onLogout` | - | `(reason)` `'logout'` 主动退出、`'expired'` 会话失效 |
|
|
192
|
+
|
|
193
|
+
---
|
|
106
194
|
|
|
107
|
-
##
|
|
195
|
+
## 完整 API
|
|
108
196
|
|
|
109
|
-
|
|
110
|
-
|
|
197
|
+
| 导出 | 说明 |
|
|
198
|
+
|---|---|
|
|
199
|
+
| `setup(options)` | 初始化,每个应用一次 |
|
|
200
|
+
| `login(submitApi, params)` | 完整登录流程,返回 `state` |
|
|
201
|
+
| `logout()` | 退出(凭证过期会先续期再退,保证服务端会话被删) |
|
|
202
|
+
| `request(api, data?, options?)` | 业务请求,返回 `data`;自动静默恢复 / 续期 / 重试一次 |
|
|
203
|
+
| `upload(api, file, data?, options?)` | multipart 上传;`options.timeout` 可单独放宽 |
|
|
204
|
+
| `isLogin()` | 本地登录态(同步,不发请求) |
|
|
205
|
+
| `getState()` | `{mode, loggedIn, hasAccess, sid, ds}` |
|
|
206
|
+
| `verifyLogin({force?})` | 服务端确认登录态;`{force:true}` 强制换一次凭证 |
|
|
207
|
+
| `getMode()` | `'cookie'` / `'sign'` |
|
|
208
|
+
| `clear()` | 只清本地(不调服务端) |
|
|
209
|
+
| `expire(reason?)` | 判定失效:清本地 + 回调 +(`enableAuth` 时)跳登录页 |
|
|
210
|
+
| `auth` | 门面:`{login, logout, isLogin, getState, restore}` |
|
|
211
|
+
| `store` | 存储视图(`access` / `sid` / `ds` / `cookie` / `exp`),一般不用直接碰 |
|
|
212
|
+
| `BizError` / `AuthError` / `CODE` / `isAuthError` | 错误类型与码值 |
|
|
213
|
+
|
|
214
|
+
> `refresh` **不导出**:后端规定凭证必须已过期才允许续期,手动调会把会话弄坏。续期由 SDK 在收到 `500900` 后自动做。
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 错误处理
|
|
219
|
+
|
|
220
|
+
后端业务错误统一是 HTTP 200 + `{code, message, data}`;只有框架级异常才是 5xx。
|
|
221
|
+
|
|
222
|
+
| code | 含义 | SDK 行为 |
|
|
223
|
+
|---|---|---|
|
|
224
|
+
| `200` | 成功 | 返回 `data` |
|
|
225
|
+
| `202` | 登录中(轮询) | 继续轮询,`pollMax` 用完报超时 |
|
|
226
|
+
| `500900` | 会话失效 | 自动续期一次 → 重发;仍失败抛 `AuthError` + `onLogout('expired')` |
|
|
227
|
+
| `500` | 通用业务错误(密码错误 / 平台不支持 / 重复请求 / 时钟异常) | 抛 `BizError` + `onError`,**不续期、不登出** |
|
|
228
|
+
| `401001` | 没有权限 | 抛 `BizError`,会话仍有效 |
|
|
229
|
+
| `403` | 非法来源(CORS / 域名不符) | 环境配置问题 |
|
|
230
|
+
| `404` | 接口不存在 | 接口没在网关 api 表登记 |
|
|
231
|
+
| `NETWORK` / `TIMEOUT` | 网络异常 / 超时 | `BizError`,**不会**登出 |
|
|
232
|
+
|
|
233
|
+
```js
|
|
234
|
+
import {BizError, isAuthError} from '@dplugin/core';
|
|
235
|
+
|
|
236
|
+
try {
|
|
237
|
+
await request('/api/safe/xxx');
|
|
238
|
+
} catch (e) {
|
|
239
|
+
if (isAuthError(e)) { /* 重新登录 */ }
|
|
240
|
+
else if (e instanceof BizError) { /* e.code / e.message */ }
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## 常见问题
|
|
247
|
+
|
|
248
|
+
**1. 报「crypto.subtle 不存在」**
|
|
249
|
+
|
|
250
|
+
`crypto.subtle` 只在**安全上下文**存在:`https://`、`file://`、`http://localhost`、`http://127.0.0.1`。
|
|
251
|
+
用内网 IP(`http://192.168.x.x`)调试就会拿不到 —— 换 localhost 或配本地 https。
|
|
252
|
+
**cookie 模式不需要 WebCrypto**,不受影响。
|
|
253
|
+
|
|
254
|
+
**2. 跨源时接口变慢 / 多了一次 OPTIONS**
|
|
255
|
+
|
|
256
|
+
SDK 用 `Content-Type: text/plain` + 参数放 query,本来就是**CORS 简单请求,不触发预检**。
|
|
257
|
+
业务侧不要给这些请求加自定义 header,否则预检又回来了。
|
|
258
|
+
|
|
259
|
+
**3. `a.com` 访问 `api.a.com` 走的是哪个模式**
|
|
260
|
+
|
|
261
|
+
**sign**。同源判定是 origin 全等:`https://a.com` ≠ `https://api.a.com`。
|
|
262
|
+
|
|
263
|
+
**4. `dsign` 为什么只出现在 URL 上、且只能是 `BIZ`**
|
|
264
|
+
|
|
265
|
+
网关只放行 URL 上的 `BIZ` 信封;换 code / 换 access / 续期的信封都放请求体里。
|
|
266
|
+
|
|
267
|
+
**5. 退出后 Cookie 还在**
|
|
268
|
+
|
|
269
|
+
不要自己清。退出接口会 `Set-Cookie` 清 `dp_sid`/`dp_token`;手动清会留下服务端孤儿会话。
|
|
270
|
+
|
|
271
|
+
**6. 登录成功但跳转后没会话**
|
|
272
|
+
|
|
273
|
+
登录页和应用必须**同源**。放 `login.xxx.com` + `app.xxx.com` 会变成「登录成功 → 跳应用 → 没会话 → 回登录页」。
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 部署要求
|
|
278
|
+
|
|
279
|
+
1. **https 或 localhost**(sign 模式):`crypto.subtle` 在非安全上下文不存在。
|
|
280
|
+
2. **登录页与应用同源**:`localStorage` / `IndexedDB` 不跨源,且后端 `sso.domain` 取的是登录时的 Origin 主机名。
|
|
281
|
+
3. **网关 CORS 白名单**要包含前端 origin(`dplugin.cors.allowed_origins`)。
|
|
282
|
+
4. **接口要在网关 api 表登记**(查不到直接 404)。
|
|
283
|
+
5. 反向代理**不要改写** `/api/**` 的路径和 query —— 签名原文包含路径。
|
|
284
|
+
6. cookie 模式下,接口域名前面的反代要能把 `Origin` 头透传(网关用它校验 `domain`)。
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## 附录:签名协议(只在需要排查时看)
|
|
289
|
+
|
|
290
|
+
四个场景共用一张模板,后端 `com.dplugin.starter.core.sign.SignUtils` 与前端 `src/sign.js` 逐字节一致
|
|
291
|
+
(有跨语言比对测试):
|
|
111
292
|
|
|
112
293
|
```
|
|
113
294
|
OP \n METHOD \n PATH \n ORIGIN(小写) \n DS \n TS(毫秒) \n SUBJECT \n DNA \n REDIRECT
|
|
114
295
|
```
|
|
115
296
|
|
|
116
|
-
固定 9
|
|
297
|
+
固定 9 段,缺失的段写 `-`。
|
|
117
298
|
|
|
118
299
|
| OP | 场景 | METHOD/PATH | SUBJECT | DNA/REDIRECT | 私钥 |
|
|
119
300
|
|---|---|---|---|---|---|
|
|
120
301
|
| `BIZ` | 业务接口(网关验) | 实际值 | access | `-` | domain |
|
|
121
302
|
| `VERIFY` | 临时 token 轮询换 code(login 验) | 实际值 | 临时 token | 都有 | sso |
|
|
122
|
-
| `VERIFY_SID` | 已登录用 sid 换 code(login
|
|
303
|
+
| `VERIFY_SID` | 已登录用 sid 换 code(login 验,**只在登录域**) | 实际值 | sid | 都有 | sso |
|
|
123
304
|
| `TOKEN` | code 换 access(login 验) | `-` | 一次性 code | dna | domain |
|
|
124
305
|
|
|
125
306
|
### 单参数信封
|
|
126
307
|
|
|
127
|
-
所有签名要素压成一个值,服务端再拆:
|
|
128
|
-
|
|
129
308
|
```
|
|
130
309
|
dsign = OP.SUBJECT.DS.TS.SIGN
|
|
131
310
|
```
|
|
@@ -134,184 +313,97 @@ dsign = OP.SUBJECT.DS.TS.SIGN
|
|
|
134
313
|
|---|---|---|
|
|
135
314
|
| 业务 `/api/**` `/mgr/**` | URL query `dsign` | body 就是业务参数 |
|
|
136
315
|
| `logout` | URL query `dsign` | 无 body |
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
|
|
140
|
-
URL 上不再有 `_dsid / _ds / _dt / dsignn` 四个参数,只有一个 `dsign`。
|
|
316
|
+
| `/s/refresh` | URL query `dsign`(OP=`BIZ`) | 无 body |
|
|
317
|
+
| `/s/verify` | body `dsign` | `dna`、`redirect` |
|
|
318
|
+
| `/s/token` | body `dsign` | `pk` |
|
|
141
319
|
|
|
142
|
-
>
|
|
143
|
-
>
|
|
144
|
-
> 测试里有一条断言守着这个不变量(`URL 上的 dsign 全部是 BIZ`)。
|
|
320
|
+
> **硬约束**:URL 上的 `dsign` **只能是 `BIZ`**;`VERIFY`/`VERIFY_SID`/`TOKEN` 必须放请求体。
|
|
321
|
+
> 测试里有一条断言守着它(`URL 上的 dsign 全部是 BIZ`)。
|
|
145
322
|
|
|
146
323
|
### 为什么 `dsign` 放 query 而不是请求头
|
|
147
324
|
|
|
148
|
-
请求体用
|
|
149
|
-
|
|
325
|
+
请求体用 `Content-Type: text/plain`(CORS 简单请求允许的类型),加上没有自定义头,
|
|
326
|
+
跨域时**不会发 OPTIONS 预检**,每个接口少一次往返。框架侧 `JSONHttpMessageConverter.body()`
|
|
327
|
+
不看 Content-Type,直接读流按 JSON 解析,所以 `text/plain` 里放 JSON 完全正常。
|
|
150
328
|
|
|
151
|
-
|
|
152
|
-
所以 `text/plain` 里放 JSON 完全正常。
|
|
329
|
+
一旦把 `dsign` 挪到 `X-Dsig` 这类自定义头,就会重新触发预检 —— 省下的往返又还回去。
|
|
153
330
|
|
|
154
|
-
|
|
155
|
-
所以「单参数信封」放在 query 上是和「无预检」配套的设计,不是随意选的。
|
|
156
|
-
|
|
157
|
-
### 其它硬约束(读代码核出来的)
|
|
331
|
+
### 其它硬约束
|
|
158
332
|
|
|
159
333
|
- `ORIGIN` 两边都转小写;`TS` 一律毫秒;
|
|
160
334
|
- `verify` / `token` 绑定 `D-Request-IP`:登录过程中 IP 变了会 `500900`;
|
|
161
|
-
- `dna` = `SHA-256(SPKI DER)` 的 Base64URL
|
|
335
|
+
- `dna` = `SHA-256(SPKI DER)` 的 Base64URL 无填充;
|
|
162
336
|
- 时间窗 300 秒;access Redis TTL 1800 秒;临时 token 5 分钟;code 60 秒且 `GETDEL`;
|
|
163
|
-
- 设备只走信封的 `DS`
|
|
164
|
-
- 业务请求头里只有 `Content-Type: text/plain`,不加自定义头 → 不触发 CORS 预检(有测试断言)。
|
|
337
|
+
- 设备只走信封的 `DS` 段,没有 `X-Device-Id` 头。
|
|
165
338
|
|
|
166
|
-
##
|
|
167
|
-
|
|
168
|
-
| 码 | 含义 | SDK 已自动处理,业务侧只需 |
|
|
169
|
-
|---|---|---|
|
|
170
|
-
| `200` | 成功 | - |
|
|
171
|
-
| `202` | 登录中 | `login()` 内部轮询,业务侧看不到 |
|
|
172
|
-
| `500900` | 会话失效 | 业务请求里会自动 `refresh` 一次并重发;刷新也失败才清状态 + 跳登录页 |
|
|
173
|
-
| `500` | 通用业务错误:密码错误 / 平台不支持 / 重复请求(`重复请求`、`请勿重复提交`)/ 时钟异常 | 抛 `BizError` + `onError`,**不刷新、不登出**;按 `message` 展示即可 |
|
|
174
|
-
| `401001` | 没有权限 | 抛错 + `onError`,会话仍然有效 |
|
|
175
|
-
| `403` | 非法来源(CORS / 域名不符) | 环境配置问题,不是登录态问题 |
|
|
176
|
-
| `404` | 接口不存在 | 接口没在 api 表登记 |
|
|
177
|
-
|
|
178
|
-
> `login()` 抛出的错误直接展示即可(`code` + `message` 都来自后端)。
|
|
179
|
-
|
|
180
|
-
## 密钥与存储
|
|
339
|
+
## 附录:密钥与存储
|
|
181
340
|
|
|
182
341
|
| 内容 | 位置 | 说明 |
|
|
183
342
|
|---|---|---|
|
|
184
|
-
| `access` | localStorage `dplugin.access` |
|
|
185
|
-
| `sid` | localStorage `dplugin.sid` |
|
|
186
|
-
| `ds` | localStorage `dplugin.ds` |
|
|
187
|
-
| `exp` | localStorage `dplugin.exp` |
|
|
188
|
-
|
|
|
189
|
-
|
|
|
343
|
+
| `access` | localStorage `dplugin.access` | sign 模式业务信封的 SUBJECT,30 分钟 |
|
|
344
|
+
| `sid` | localStorage `dplugin.sid` | 静默恢复用 |
|
|
345
|
+
| `ds` | localStorage `dplugin.ds` | 设备凭证,服务端下发,**不要自己生成**;退出**不清**它(设备不是会话) |
|
|
346
|
+
| `exp` | localStorage `dplugin.exp` | 到期时间,仅用于本地展示 |
|
|
347
|
+
| `cookie` | localStorage `dplugin.cookie` | cookie 模式的「已登录」标记(HttpOnly 读不到,只能记标记) |
|
|
348
|
+
| sso 私钥 | IndexedDB `dplugin-auth/keys.sso` | 签 `VERIFY` / `VERIFY_SID` |
|
|
349
|
+
| 域私钥 | IndexedDB `dplugin-auth/keys.domain` | 签 `BIZ` / `TOKEN` |
|
|
190
350
|
|
|
191
351
|
- 私钥 `extractable = false`,只能以 CryptoKey 形式存在 IndexedDB,JS 导不出原始字节。
|
|
192
352
|
- 每次登录重新生成 sso 密钥,每次换 token 重新生成域密钥(多账号不会串)。
|
|
193
|
-
- 清过 IndexedDB
|
|
353
|
+
- 清过 IndexedDB 后:业务请求发现缺私钥 → 用 `sid` 强制换一次 token 自愈;`sid` 也没了才回登录页。
|
|
194
354
|
|
|
195
|
-
##
|
|
355
|
+
## 附录:行为约定
|
|
196
356
|
|
|
197
|
-
1. **同一页面内续期单飞**:N 个并发 500900
|
|
198
|
-
2. **跨标签页续期**:`/s/token` 有按 sso 的锁,A
|
|
199
|
-
|
|
200
|
-
3.
|
|
201
|
-
|
|
202
|
-
4. **`isLogin()`
|
|
203
|
-
用 sid 静默换回 access;两条路都断了才跳登录页。
|
|
357
|
+
1. **同一页面内续期单飞**:N 个并发 `500900` 只发一次续期,其余复用同一结果。
|
|
358
|
+
2. **跨标签页续期**:`/s/token` 有按 sso 的锁,A 抢到时 B 会拿到 `500 重复请求`;SDK 不登出,等 A 把新
|
|
359
|
+
access 写进 localStorage(最多 1.2 秒)后直接采用。cookie 模式因为 Cookie 天然共享,由后端锁兜住。
|
|
360
|
+
3. **登录失败回滚密钥**:`login()` 失败(密码错、轮询超时)会把上一个会话的密钥写回去,
|
|
361
|
+
避免「输错一次密码」把已有会话的私钥冲掉。
|
|
362
|
+
4. **`isLogin()` 只是提示**:真正有效性以第一次 `request()` 为准。
|
|
204
363
|
|
|
205
|
-
##
|
|
364
|
+
## 附录:已知取舍(有意为之)
|
|
206
365
|
|
|
207
366
|
| 取舍 | 原因 |
|
|
208
367
|
|---|---|
|
|
209
|
-
| 不做定时器 / 提前续期 |
|
|
210
|
-
| 默认不跳登录页(`enableAuth:false`) |
|
|
211
|
-
| `refresh`
|
|
212
|
-
| 不做跨标签页登出广播 | A
|
|
213
|
-
| 不内置 loading / 重试策略 |
|
|
214
|
-
| QQ / 微信扫码登录暂不支持 |
|
|
215
|
-
|
|
216
|
-
## 原生能力指纹(防 fetch / indexedDB.open / subtle 被代理)
|
|
217
|
-
|
|
218
|
-
`src/native.js` 在 **模块加载那一刻**:
|
|
219
|
-
1. 把 `fetch`、`indexedDB.open`、`crypto.subtle.{generateKey,exportKey,importKey,sign,verify,digest}`
|
|
220
|
-
绑定成局部引用 —— 之后页面再替换全局,也影响不到 SDK;
|
|
221
|
-
2. 顺手给这份引用做**指纹校验**,`setup()` 时报告(`nativeGuard: 'warn' | 'error' | 'off'`)。
|
|
222
|
-
|
|
223
|
-
真机(Chrome)实测结果,`checkNative()` 的返回:
|
|
224
|
-
|
|
225
|
-
| 场景 | 返回 | 判定依据 |
|
|
226
|
-
|---|---|---|
|
|
227
|
-
| 原生 | `[]` | `function fetch() { [native code] }` |
|
|
228
|
-
| JS 包装(转发原生) | `["fetch"]` | 源码变成 `async function fetch(input, init) {…}` |
|
|
229
|
-
| **Proxy 包原生** | `["fetch"]` | Proxy 的源码是 `function () { [native code] }` —— **没有函数名** |
|
|
230
|
-
| 自造 fetch(不校验参数) | `["fetch"]` | 源码里没有 `[native code]` |
|
|
231
|
-
| `indexedDB.open` 被包 | `["indexedDB.open"]` | 源码形态 + **无参调用必须同步抛缺参数 TypeError** |
|
|
232
|
-
| 全部还原 | `[]` | - |
|
|
233
|
-
|
|
234
|
-
关键细节(实测踩出来的):
|
|
235
|
-
- **`fetch()` 无参在 Chrome 里是返回 rejected promise,不是同步抛**。所以 fetch 只用「源码形态」
|
|
236
|
-
判,不能做同步异常指纹,否则会把原生误报成被替换。
|
|
237
|
-
- `indexedDB.open()` 是同步 WebIDL 方法,无参会同步抛
|
|
238
|
-
`TypeError: Failed to execute 'open' on 'IDBFactory': 1 argument required…`,
|
|
239
|
-
所以它额外多一道异常指纹。`crypto.subtle.*` 同理是异步 reject,只比源码。
|
|
240
|
-
- 检测只对浏览器生效:Node / SSR 里 fetch、subtle 本身就是 JS 实现,必然误报。
|
|
241
|
-
|
|
242
|
-
**挡不住的**:在本模块加载之前就用 Proxy 冒充并同步伪造 `name` / 源码,或者干脆接管整个 `window`
|
|
243
|
-
(同源 XSS)。同源脚本本来就能自己开 IndexedDB、读 localStorage,patch 只是省事,所以这里是
|
|
244
|
-
「提高门槛」,真正的边界是:私钥不可导出 + 签名绑路径/设备/时间/token + 网关 lockSign + 30 分钟 TTL。
|
|
245
|
-
|
|
246
|
-
> 要更硬的隔离只有换 realm:一次性 same-origin iframe(或 Worker)取 `contentWindow.fetch` /
|
|
247
|
-
> `contentWindow.indexedDB.open`,页面对主 realm 的 patch 影响不到它。代价:CSP 放行 `frame-src`、
|
|
248
|
-
> iframe 生命周期、跨 realm 传对象。默认没做。
|
|
249
|
-
|
|
250
|
-
浏览器自检页:`test/native-check.html`(起静态服务打开,逐项替换 → 看返回)。
|
|
251
|
-
|
|
252
|
-
## 部署要求
|
|
253
|
-
|
|
254
|
-
1. **必须 https 或 localhost**:`crypto.subtle` 在非安全上下文不存在,SDK 会直接抛错。
|
|
255
|
-
2. **登录页和应用必须同源**(同 scheme+host+port):
|
|
256
|
-
- `localStorage` / `IndexedDB` 不跨源,跨子域登录拿不到会话;
|
|
257
|
-
- 后端 `sso.domain` 取的是登录时的 Origin 主机名(不是可注册域),所以每个子域各自登录。
|
|
258
|
-
把登录页放在 `login.xxx.com`、应用在 `app.xxx.com`,会变成「登录成功 → 跳应用 → 没会话 → 回登录页」的死循环。
|
|
259
|
-
3. **网关 CORS 白名单**要包含前端的 origin(`dplugin.cors.allowed_origins`)。
|
|
260
|
-
4. **登录相关接口必须在 api 表登记**(网关 `AuthFilter` 查不到就 404)。
|
|
261
|
-
5. 反向代理不要改写 `/api/**` 的路径和 query —— `dsignn` 的签名原文包含路径。
|
|
262
|
-
|
|
263
|
-
## 与旧版的差异(迁移清单)
|
|
264
|
-
|
|
265
|
-
| 旧 | 新 |
|
|
266
|
-
|---|---|
|
|
267
|
-
| `request(api, {data, loading, noToken})` | `request(api, data, options)` |
|
|
268
|
-
| `auth.setAuthData(data)` | 不需要,`login()` 内部落库 |
|
|
269
|
-
| `auth.jump(token)` / `jumpGenerate()` | **删除**(后端 jump 接口已删) |
|
|
270
|
-
| `setup({publicKey})` | 不需要(改用 WebCrypto 每次生成) |
|
|
271
|
-
| `onError(data)` | `onError({code, message, error})`,签名兼容 |
|
|
272
|
-
| 页面里 `localStorage.token` | `store.access`(键名 `dplugin.access`) |
|
|
273
|
-
| `utils/device.js` 里的 `platform` 依赖 | SDK 内置 `deviceInfo()`,`login()` 自动带 |
|
|
368
|
+
| 不做定时器 / 提前续期 | 后端规定凭证必须**已过期**才允许续期,提前续期会被判异常并吊销整个 sso |
|
|
369
|
+
| 默认不跳登录页(`enableAuth:false`) | 框架不该替业务决定导航 |
|
|
370
|
+
| `refresh` 不导出 | 同上,业务手调会把用户全端踢下线 |
|
|
371
|
+
| 不做跨标签页登出广播 | A 退出后 B 要等下一个请求才发现;加 `storage` 监听收益不值 |
|
|
372
|
+
| 不内置 loading / 重试策略 | SDK 只保证「登录态 + 签名」正确 |
|
|
373
|
+
| QQ / 微信扫码登录暂不支持 | 后端这两个入口还没接新协议 |
|
|
274
374
|
|
|
275
|
-
##
|
|
375
|
+
## 附录:原生能力指纹(防 fetch / indexedDB.open 被代理)
|
|
276
376
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
```
|
|
377
|
+
`src/native.js` 在**模块加载那一刻**把 `fetch`、`indexedDB.open`、`crypto.subtle.*` 绑成局部引用,
|
|
378
|
+
之后页面再替换全局也影响不到 SDK;顺手做源码指纹校验,`setup()` 时报告
|
|
379
|
+
(`nativeGuard: 'warn' | 'error' | 'off'`)。
|
|
281
380
|
|
|
282
|
-
|
|
381
|
+
挡不住的是「在本模块之前就用 Proxy 冒充并伪造源码」或同源 XSS 接管 `window` ——
|
|
382
|
+
这一层只是提高门槛,真正的边界是:私钥不可导出 + 签名绑路径/设备/时间 + 网关 lockSign + 30 分钟 TTL。
|
|
283
383
|
|
|
284
|
-
|
|
384
|
+
---
|
|
285
385
|
|
|
286
|
-
|
|
386
|
+
## 开发与发布
|
|
287
387
|
|
|
288
388
|
```bash
|
|
289
|
-
|
|
389
|
+
npm install
|
|
390
|
+
npm run build # dist/index.mjs(ESM) + index.cjs(CJS) + index.umd.js(UMD/DPluginCore)
|
|
391
|
+
npm test # 两套自检:39 次请求(sign)+ 22 项(cookie)
|
|
392
|
+
node test/interop.mjs # 改了签名相关代码后跑:输出 {pk, text, sign} 供后端验签
|
|
290
393
|
```
|
|
291
394
|
|
|
292
|
-
|
|
395
|
+
发布:
|
|
293
396
|
|
|
294
397
|
```bash
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
# 两边 pk 必须一致、extractable 必须为 false
|
|
398
|
+
npm version patch # 或 minor / major
|
|
399
|
+
npm run build && npm test
|
|
400
|
+
npm publish --registry=https://registry.npmjs.org/
|
|
299
401
|
```
|
|
300
402
|
|
|
301
|
-
|
|
403
|
+
- 安装走国内镜像没问题(`registry.npmmirror.com` 会自动同步);
|
|
404
|
+
- **发布/查询版本必须显式指定官方源** `--registry=https://registry.npmjs.org/`;
|
|
405
|
+
- 账号开了 2FA 时,token 需要勾 **Bypass 2FA**,否则 `npm publish` 会 403。
|
|
302
406
|
|
|
303
|
-
|
|
304
|
-
import com.dplugin.core.utils.EcdsaUtils;
|
|
407
|
+
## License
|
|
305
408
|
|
|
306
|
-
|
|
307
|
-
public static void main(String[] a) {
|
|
308
|
-
System.out.println(EcdsaUtils.verify(a[0], a[1], a[2]) ? "VERIFY_OK" : "VERIFY_FAIL");
|
|
309
|
-
}
|
|
310
|
-
}
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
JAR=$(ls ~/.m2/repository/com/dplugin/dplugin-core/*/dplugin-core-*.jar | grep -v sources | tail -1)
|
|
315
|
-
javac -cp "$JAR" EcdsaVerify.java
|
|
316
|
-
java -cp "$JAR:." EcdsaVerify '<pk>' '<text>' '<sign>'
|
|
317
|
-
```
|
|
409
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dplugin/core",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.1",
|
|
4
4
|
"description": "DPlugin 前端登录与请求 SDK(同域 Cookie + 跨域 ECDSA 双模式)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -34,14 +34,6 @@
|
|
|
34
34
|
"engines": {
|
|
35
35
|
"node": ">=18"
|
|
36
36
|
},
|
|
37
|
-
"repository": {
|
|
38
|
-
"type": "git",
|
|
39
|
-
"url": "git+https://github.com/dplugin/dplugin-login.git"
|
|
40
|
-
},
|
|
41
|
-
"homepage": "https://github.com/dplugin/dplugin-login/tree/main/dplugin-login-umdjs-core",
|
|
42
|
-
"bugs": {
|
|
43
|
-
"url": "https://github.com/dplugin/dplugin-login/issues"
|
|
44
|
-
},
|
|
45
37
|
"publishConfig": {
|
|
46
38
|
"access": "public"
|
|
47
39
|
},
|