@dplugin/core 2.0.1 → 2.0.2
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 +82 -264
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,74 +1,55 @@
|
|
|
1
1
|
# @dplugin/core
|
|
2
2
|
|
|
3
|
-
DPlugin 前端登录与请求 SDK
|
|
4
|
-
`fetch` + `WebCrypto`。
|
|
3
|
+
DPlugin 前端登录与请求 SDK。零运行时依赖,使用浏览器原生 `fetch` 与 `WebCrypto`。
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
## 两种模式
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
按「页面地址」与「接口地址」是否同源自动选择,业务代码不用区分:
|
|
8
|
+
|
|
9
|
+
| 模式 | 触发条件 | 凭证位置 | 请求形态 |
|
|
9
10
|
|---|---|---|---|
|
|
10
|
-
| **cookie** |
|
|
11
|
-
| **sign** | 页面与接口**跨源** |
|
|
11
|
+
| **cookie** | 页面与接口**同源** | 服务端下发的 HttpOnly Cookie | 无签名参数,浏览器自动携带 Cookie |
|
|
12
|
+
| **sign** | 页面与接口**跨源** | 浏览器 localStorage | 每次请求多一个 `dsign` 参数 |
|
|
12
13
|
|
|
13
14
|
```js
|
|
14
|
-
setup({apiBase: ''}) // 同源
|
|
15
|
-
setup({apiBase: 'https://api.other.com'}) // 跨源
|
|
16
|
-
setup({apiBase: '', mode: 'sign'}) //
|
|
15
|
+
setup({apiBase: ''}) // 同源 → cookie
|
|
16
|
+
setup({apiBase: 'https://api.other.com'}) // 跨源 → sign
|
|
17
|
+
setup({apiBase: '', mode: 'sign'}) // 也可以用 mode 强制指定
|
|
17
18
|
```
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
---
|
|
20
|
+
同源按 **origin 全等**判断:`https://a.com` 与 `https://api.a.com` 算跨源。
|
|
22
21
|
|
|
23
22
|
## 安装
|
|
24
23
|
|
|
25
|
-
**npm**
|
|
26
|
-
|
|
27
24
|
```bash
|
|
28
25
|
npm i @dplugin/core
|
|
29
26
|
```
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
CDN(挂到 `window.DPluginCore`):
|
|
32
29
|
|
|
33
30
|
```html
|
|
34
|
-
<script src="https://unpkg.com/@dplugin/core@2.0.
|
|
31
|
+
<script src="https://unpkg.com/@dplugin/core@2.0.1/dist/index.umd.js"></script>
|
|
35
32
|
<script>
|
|
36
33
|
const {setup, login, request, logout} = window.DPluginCore;
|
|
37
34
|
</script>
|
|
38
35
|
```
|
|
39
36
|
|
|
40
|
-
**本地源码调试**(还没发版时)
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# 本目录先构建一次,dist/ 不入库
|
|
44
|
-
npm install && npm run build
|
|
45
|
-
|
|
46
|
-
# 页面 package.json
|
|
47
|
-
"@dplugin/core": "file:../dplugin-login-umdjs-core"
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
---
|
|
51
|
-
|
|
52
37
|
## 快速上手
|
|
53
38
|
|
|
54
|
-
### 1
|
|
39
|
+
### 1. 初始化(每个应用调一次)
|
|
55
40
|
|
|
56
41
|
```js
|
|
57
|
-
// main.js
|
|
58
42
|
import {setup} from '@dplugin/core';
|
|
59
43
|
|
|
60
44
|
setup({
|
|
61
45
|
apiBase: import.meta.env.VITE_API_BASE_URL, // '' = 同源
|
|
62
46
|
loginUrl: '/login/',
|
|
63
|
-
onError: ({code, message}) => {
|
|
64
|
-
// 业务错误统一提示(登录态的 500900 不会走到这里)
|
|
65
|
-
Modal.error({title: '操作失败[' + code + ']', content: message});
|
|
66
|
-
},
|
|
47
|
+
onError: ({code, message}) => Modal.error({title: `操作失败[${code}]`, content: message}),
|
|
67
48
|
onLogout: () => router.replace('/login')
|
|
68
49
|
});
|
|
69
50
|
```
|
|
70
51
|
|
|
71
|
-
### 2
|
|
52
|
+
### 2. 登录
|
|
72
53
|
|
|
73
54
|
```js
|
|
74
55
|
import {login} from '@dplugin/core';
|
|
@@ -77,35 +58,27 @@ await login('/api/unsafe/dplugin/user/login/pwd/submit', {username, password});
|
|
|
77
58
|
location.href = '/';
|
|
78
59
|
```
|
|
79
60
|
|
|
80
|
-
|
|
61
|
+
传的是某一种登录方式的提交接口,换手机验证码登录只是换接口和参数:
|
|
81
62
|
|
|
82
63
|
```js
|
|
83
64
|
await login('/api/unsafe/dplugin/user/login/phone/submit', {phone, code});
|
|
84
65
|
```
|
|
85
66
|
|
|
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) 业务请求
|
|
67
|
+
### 3. 请求接口
|
|
94
68
|
|
|
95
69
|
```js
|
|
96
70
|
import {request} from '@dplugin/core';
|
|
97
71
|
|
|
98
|
-
// 返回值就是后端 data
|
|
99
72
|
const user = await request('/api/safe/dplugin/user/get');
|
|
100
73
|
await request('/api/safe/dplugin/user/update', {nickname: 'x'});
|
|
101
74
|
|
|
102
|
-
//
|
|
75
|
+
// 不需要登录态的接口
|
|
103
76
|
const setting = await request('/api/unsafe/dplugin/login/page/setting', {}, {auth: false});
|
|
104
77
|
```
|
|
105
78
|
|
|
106
|
-
|
|
79
|
+
返回值就是接口的 `data`;失败抛 `BizError`,同时触发一次 `onError`。
|
|
107
80
|
|
|
108
|
-
### 4
|
|
81
|
+
### 4. 上传文件
|
|
109
82
|
|
|
110
83
|
```js
|
|
111
84
|
import {upload} from '@dplugin/core';
|
|
@@ -113,122 +86,92 @@ import {upload} from '@dplugin/core';
|
|
|
113
86
|
await upload('/api/safe/dplugin/storage/upload', file, {bizType: 'avatar'}, {timeout: 60000});
|
|
114
87
|
```
|
|
115
88
|
|
|
116
|
-
### 5
|
|
89
|
+
### 5. 退出
|
|
117
90
|
|
|
118
91
|
```js
|
|
119
92
|
import {logout} from '@dplugin/core';
|
|
120
|
-
await logout();
|
|
93
|
+
await logout();
|
|
121
94
|
```
|
|
122
95
|
|
|
123
|
-
---
|
|
124
|
-
|
|
125
96
|
## 判断登录态
|
|
126
97
|
|
|
127
98
|
```js
|
|
128
99
|
import {isLogin, getState, verifyLogin} from '@dplugin/core';
|
|
129
100
|
|
|
130
|
-
isLogin();
|
|
131
|
-
getState();
|
|
132
|
-
await verifyLogin()
|
|
101
|
+
isLogin(); // 同步、不发请求
|
|
102
|
+
getState(); // {mode, loggedIn, hasAccess, sid, ds}
|
|
103
|
+
await verifyLogin(); // 可选:向服务端确认一次,返回 boolean
|
|
133
104
|
```
|
|
134
105
|
|
|
135
|
-
|
|
106
|
+
`isLogin()` 只是本地提示,不代表一定有效:
|
|
136
107
|
|
|
137
|
-
-
|
|
138
|
-
-
|
|
108
|
+
- sign:本地有凭证即为 true,过期后第一次请求会自动换新的
|
|
109
|
+
- cookie:凭证在 HttpOnly Cookie 内,脚本读不到,只代表登录过
|
|
139
110
|
|
|
140
|
-
|
|
111
|
+
真正是否有效,以第一次 `request()` 的结果为准。
|
|
141
112
|
|
|
142
|
-
|
|
143
|
-
// 页面加载时的典型写法
|
|
144
|
-
if (!isLogin()) {
|
|
145
|
-
router.replace('/login');
|
|
146
|
-
} else {
|
|
147
|
-
// 可选:需要准确判断时再打一次服务端
|
|
148
|
-
// if (!await verifyLogin()) router.replace('/login');
|
|
149
|
-
}
|
|
150
|
-
```
|
|
113
|
+
## 会话过期会自动处理
|
|
151
114
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
## 会话失效会自动续期
|
|
155
|
-
|
|
156
|
-
业务请求返回 `500900` 时,SDK 自动续期一次再重发:
|
|
157
|
-
|
|
158
|
-
| 模式 | 续期 |
|
|
159
|
-
|---|---|
|
|
160
|
-
| cookie | `POST /api/unsafe/dplugin/login/c/refresh`(凭 Cookie,无参数) |
|
|
161
|
-
| sign | `POST /api/unsafe/dplugin/login/s/refresh?dsign=…`(`BIZ` 信封,subject = 当前 access) |
|
|
162
|
-
|
|
163
|
-
所以业务侧不用写任何续期逻辑:
|
|
115
|
+
接口返回 `500900` 时,SDK 会自动续期一次并重发这次请求,业务侧不需要写续期逻辑:
|
|
164
116
|
|
|
165
117
|
```js
|
|
166
118
|
try {
|
|
167
119
|
const data = await request('/api/safe/xxx');
|
|
168
120
|
} catch (e) {
|
|
169
121
|
if (isAuthError(e)) {
|
|
170
|
-
//
|
|
122
|
+
// 需要重新登录(onLogout 已回调过)
|
|
171
123
|
}
|
|
172
124
|
}
|
|
173
125
|
```
|
|
174
126
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
## 配置项(`setup`)
|
|
127
|
+
## 配置项
|
|
178
128
|
|
|
179
129
|
| 字段 | 默认 | 说明 |
|
|
180
130
|
|---|---|---|
|
|
181
|
-
| `apiBase` | `''` |
|
|
131
|
+
| `apiBase` | `''` | 接口前缀,`''` 表示同源 |
|
|
182
132
|
| `mode` | `'auto'` | `'auto'` / `'cookie'` / `'sign'` |
|
|
183
|
-
| `loginUrl` | `'/login/'` |
|
|
184
|
-
| `enableAuth` | `false` |
|
|
133
|
+
| `loginUrl` | `'/login/'` | 仅在 `enableAuth: true` 时用于跳转 |
|
|
134
|
+
| `enableAuth` | `false` | 默认不跳转:失效只回调 `onLogout` 并抛 `AuthError` |
|
|
185
135
|
| `timeout` | `15000` | 请求超时(毫秒) |
|
|
186
136
|
| `pollInterval` | `2000` | 登录轮询间隔(毫秒) |
|
|
187
|
-
| `pollMax` | `5` |
|
|
188
|
-
| `nativeGuard` | `'warn'` |
|
|
189
|
-
| `onError` | - | `({code, message, error})`
|
|
190
|
-
| `onLogin` | - | `(state)`
|
|
191
|
-
| `onLogout` | - | `(reason)
|
|
137
|
+
| `pollMax` | `5` | 登录轮询次数 |
|
|
138
|
+
| `nativeGuard` | `'warn'` | 浏览器能力自检:`warn` / `error` / `off` |
|
|
139
|
+
| `onError` | - | `({code, message, error})` |
|
|
140
|
+
| `onLogin` | - | `(state)` |
|
|
141
|
+
| `onLogout` | - | `(reason)`,`'logout'` 或 `'expired'` |
|
|
192
142
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
## 完整 API
|
|
143
|
+
## API
|
|
196
144
|
|
|
197
145
|
| 导出 | 说明 |
|
|
198
146
|
|---|---|
|
|
199
|
-
| `setup(options)` |
|
|
200
|
-
| `login(submitApi, params)` |
|
|
201
|
-
| `logout()` |
|
|
202
|
-
| `request(api, data?, options?)` |
|
|
203
|
-
| `upload(api, file, data?, options?)` |
|
|
204
|
-
| `isLogin()` |
|
|
147
|
+
| `setup(options)` | 初始化 |
|
|
148
|
+
| `login(submitApi, params)` | 登录,返回 `Promise<state>` |
|
|
149
|
+
| `logout()` | 退出 |
|
|
150
|
+
| `request(api, data?, options?)` | 请求接口,返回 `data` |
|
|
151
|
+
| `upload(api, file, data?, options?)` | 上传文件 |
|
|
152
|
+
| `isLogin()` | 本地登录态(同步) |
|
|
205
153
|
| `getState()` | `{mode, loggedIn, hasAccess, sid, ds}` |
|
|
206
|
-
| `verifyLogin({force?})` |
|
|
207
|
-
| `getMode()` |
|
|
208
|
-
| `clear()` |
|
|
209
|
-
| `expire(reason?)` | 判定失效:清本地 +
|
|
210
|
-
| `auth` |
|
|
211
|
-
| `store` | 存储视图(`access` / `sid` / `ds` / `cookie` / `exp`),一般不用直接碰 |
|
|
154
|
+
| `verifyLogin({force?})` | 向服务端确认登录态 |
|
|
155
|
+
| `getMode()` | 当前模式 |
|
|
156
|
+
| `clear()` | 只清本地状态 |
|
|
157
|
+
| `expire(reason?)` | 判定失效:清本地 + 回调(可选跳转) |
|
|
158
|
+
| `auth` | `{login, logout, isLogin, getState, restore}` |
|
|
212
159
|
| `BizError` / `AuthError` / `CODE` / `isAuthError` | 错误类型与码值 |
|
|
213
160
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
---
|
|
161
|
+
续期由 SDK 内部处理,`refresh` 不对外导出。
|
|
217
162
|
|
|
218
|
-
##
|
|
219
|
-
|
|
220
|
-
后端业务错误统一是 HTTP 200 + `{code, message, data}`;只有框架级异常才是 5xx。
|
|
163
|
+
## 错误码
|
|
221
164
|
|
|
222
165
|
| code | 含义 | SDK 行为 |
|
|
223
166
|
|---|---|---|
|
|
224
167
|
| `200` | 成功 | 返回 `data` |
|
|
225
|
-
| `202` |
|
|
226
|
-
| `500900` |
|
|
227
|
-
| `500` |
|
|
228
|
-
| `401001` | 没有权限 | 抛 `BizError
|
|
229
|
-
| `403` |
|
|
230
|
-
| `404` | 接口不存在 |
|
|
231
|
-
| `NETWORK` / `TIMEOUT` | 网络异常 / 超时 | `BizError
|
|
168
|
+
| `202` | 登录中 | 自动轮询,业务不用管 |
|
|
169
|
+
| `500900` | 登录态失效 | 自动续期一次并重发;仍失败抛 `AuthError` 并触发 `onLogout('expired')` |
|
|
170
|
+
| `500` | 业务错误(如密码错误、重复提交) | 抛 `BizError` + `onError`,不登出 |
|
|
171
|
+
| `401001` | 没有权限 | 抛 `BizError`,登录态仍有效 |
|
|
172
|
+
| `403` | 来源不被允许 | 抛 `BizError` |
|
|
173
|
+
| `404` | 接口不存在 | 抛 `BizError` |
|
|
174
|
+
| `NETWORK` / `TIMEOUT` | 网络异常 / 超时 | 抛 `BizError`,不登出 |
|
|
232
175
|
|
|
233
176
|
```js
|
|
234
177
|
import {BizError, isAuthError} from '@dplugin/core';
|
|
@@ -241,169 +184,44 @@ try {
|
|
|
241
184
|
}
|
|
242
185
|
```
|
|
243
186
|
|
|
244
|
-
---
|
|
245
|
-
|
|
246
187
|
## 常见问题
|
|
247
188
|
|
|
248
|
-
|
|
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`。
|
|
189
|
+
**报「crypto.subtle 不存在」**
|
|
262
190
|
|
|
263
|
-
|
|
191
|
+
sign 模式依赖 WebCrypto,它只在安全上下文里存在:`https://`、`file://`、`http://localhost`、`http://127.0.0.1`。
|
|
192
|
+
用内网 IP(`http://192.168.x.x`)调试时拿不到,换 localhost 或本地 https 即可。cookie 模式不受影响。
|
|
264
193
|
|
|
265
|
-
|
|
194
|
+
**跨源时请求变慢**
|
|
266
195
|
|
|
267
|
-
|
|
196
|
+
SDK 发的是 CORS「简单请求」,不会触发 OPTIONS 预检。业务侧不要给这些请求额外加自定义请求头,否则预检又回来了。
|
|
268
197
|
|
|
269
|
-
|
|
198
|
+
**`a.com` 调用 `api.a.com` 用哪个模式**
|
|
270
199
|
|
|
271
|
-
|
|
200
|
+
sign。同源要求协议、主机、端口完全一致。
|
|
272
201
|
|
|
273
|
-
|
|
202
|
+
**退出后 Cookie 还在**
|
|
274
203
|
|
|
275
|
-
|
|
204
|
+
不要手动清。退出接口负责清理,脚本自己清会留下无效会话。
|
|
276
205
|
|
|
277
|
-
|
|
206
|
+
**登录成功、跳转后却没有登录态**
|
|
278
207
|
|
|
279
|
-
|
|
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`)。
|
|
208
|
+
登录页与应用必须在同一个 origin。放在两个不同域名下,浏览器存储不共享,会形成「登录 → 跳转 → 无会话 → 回登录页」。
|
|
285
209
|
|
|
286
|
-
|
|
210
|
+
## 环境要求
|
|
287
211
|
|
|
288
|
-
|
|
212
|
+
1. sign 模式需要 `https` 或 `localhost`(WebCrypto 的要求)。
|
|
213
|
+
2. cookie 模式要求页面与接口同源。
|
|
214
|
+
3. 跨源部署时,接口侧需允许该页面的 origin(CORS)。
|
|
215
|
+
4. 反向代理不要改写接口路径和查询参数。
|
|
289
216
|
|
|
290
|
-
|
|
291
|
-
(有跨语言比对测试):
|
|
292
|
-
|
|
293
|
-
```
|
|
294
|
-
OP \n METHOD \n PATH \n ORIGIN(小写) \n DS \n TS(毫秒) \n SUBJECT \n DNA \n REDIRECT
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
固定 9 段,缺失的段写 `-`。
|
|
298
|
-
|
|
299
|
-
| OP | 场景 | METHOD/PATH | SUBJECT | DNA/REDIRECT | 私钥 |
|
|
300
|
-
|---|---|---|---|---|---|
|
|
301
|
-
| `BIZ` | 业务接口(网关验) | 实际值 | access | `-` | domain |
|
|
302
|
-
| `VERIFY` | 临时 token 轮询换 code(login 验) | 实际值 | 临时 token | 都有 | sso |
|
|
303
|
-
| `VERIFY_SID` | 已登录用 sid 换 code(login 验,**只在登录域**) | 实际值 | sid | 都有 | sso |
|
|
304
|
-
| `TOKEN` | code 换 access(login 验) | `-` | 一次性 code | dna | domain |
|
|
305
|
-
|
|
306
|
-
### 单参数信封
|
|
307
|
-
|
|
308
|
-
```
|
|
309
|
-
dsign = OP.SUBJECT.DS.TS.SIGN
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
| 接口 | 携带位置 | 其它字段 |
|
|
313
|
-
|---|---|---|
|
|
314
|
-
| 业务 `/api/**` `/mgr/**` | URL query `dsign` | body 就是业务参数 |
|
|
315
|
-
| `logout` | URL query `dsign` | 无 body |
|
|
316
|
-
| `/s/refresh` | URL query `dsign`(OP=`BIZ`) | 无 body |
|
|
317
|
-
| `/s/verify` | body `dsign` | `dna`、`redirect` |
|
|
318
|
-
| `/s/token` | body `dsign` | `pk` |
|
|
319
|
-
|
|
320
|
-
> **硬约束**:URL 上的 `dsign` **只能是 `BIZ`**;`VERIFY`/`VERIFY_SID`/`TOKEN` 必须放请求体。
|
|
321
|
-
> 测试里有一条断言守着它(`URL 上的 dsign 全部是 BIZ`)。
|
|
322
|
-
|
|
323
|
-
### 为什么 `dsign` 放 query 而不是请求头
|
|
324
|
-
|
|
325
|
-
请求体用 `Content-Type: text/plain`(CORS 简单请求允许的类型),加上没有自定义头,
|
|
326
|
-
跨域时**不会发 OPTIONS 预检**,每个接口少一次往返。框架侧 `JSONHttpMessageConverter.body()`
|
|
327
|
-
不看 Content-Type,直接读流按 JSON 解析,所以 `text/plain` 里放 JSON 完全正常。
|
|
328
|
-
|
|
329
|
-
一旦把 `dsign` 挪到 `X-Dsig` 这类自定义头,就会重新触发预检 —— 省下的往返又还回去。
|
|
330
|
-
|
|
331
|
-
### 其它硬约束
|
|
332
|
-
|
|
333
|
-
- `ORIGIN` 两边都转小写;`TS` 一律毫秒;
|
|
334
|
-
- `verify` / `token` 绑定 `D-Request-IP`:登录过程中 IP 变了会 `500900`;
|
|
335
|
-
- `dna` = `SHA-256(SPKI DER)` 的 Base64URL 无填充;
|
|
336
|
-
- 时间窗 300 秒;access Redis TTL 1800 秒;临时 token 5 分钟;code 60 秒且 `GETDEL`;
|
|
337
|
-
- 设备只走信封的 `DS` 段,没有 `X-Device-Id` 头。
|
|
338
|
-
|
|
339
|
-
## 附录:密钥与存储
|
|
340
|
-
|
|
341
|
-
| 内容 | 位置 | 说明 |
|
|
342
|
-
|---|---|---|
|
|
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` |
|
|
350
|
-
|
|
351
|
-
- 私钥 `extractable = false`,只能以 CryptoKey 形式存在 IndexedDB,JS 导不出原始字节。
|
|
352
|
-
- 每次登录重新生成 sso 密钥,每次换 token 重新生成域密钥(多账号不会串)。
|
|
353
|
-
- 清过 IndexedDB 后:业务请求发现缺私钥 → 用 `sid` 强制换一次 token 自愈;`sid` 也没了才回登录页。
|
|
354
|
-
|
|
355
|
-
## 附录:行为约定
|
|
356
|
-
|
|
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()` 为准。
|
|
363
|
-
|
|
364
|
-
## 附录:已知取舍(有意为之)
|
|
365
|
-
|
|
366
|
-
| 取舍 | 原因 |
|
|
367
|
-
|---|---|
|
|
368
|
-
| 不做定时器 / 提前续期 | 后端规定凭证必须**已过期**才允许续期,提前续期会被判异常并吊销整个 sso |
|
|
369
|
-
| 默认不跳登录页(`enableAuth:false`) | 框架不该替业务决定导航 |
|
|
370
|
-
| `refresh` 不导出 | 同上,业务手调会把用户全端踢下线 |
|
|
371
|
-
| 不做跨标签页登出广播 | A 退出后 B 要等下一个请求才发现;加 `storage` 监听收益不值 |
|
|
372
|
-
| 不内置 loading / 重试策略 | SDK 只保证「登录态 + 签名」正确 |
|
|
373
|
-
| QQ / 微信扫码登录暂不支持 | 后端这两个入口还没接新协议 |
|
|
374
|
-
|
|
375
|
-
## 附录:原生能力指纹(防 fetch / indexedDB.open 被代理)
|
|
376
|
-
|
|
377
|
-
`src/native.js` 在**模块加载那一刻**把 `fetch`、`indexedDB.open`、`crypto.subtle.*` 绑成局部引用,
|
|
378
|
-
之后页面再替换全局也影响不到 SDK;顺手做源码指纹校验,`setup()` 时报告
|
|
379
|
-
(`nativeGuard: 'warn' | 'error' | 'off'`)。
|
|
380
|
-
|
|
381
|
-
挡不住的是「在本模块之前就用 Proxy 冒充并伪造源码」或同源 XSS 接管 `window` ——
|
|
382
|
-
这一层只是提高门槛,真正的边界是:私钥不可导出 + 签名绑路径/设备/时间 + 网关 lockSign + 30 分钟 TTL。
|
|
383
|
-
|
|
384
|
-
---
|
|
385
|
-
|
|
386
|
-
## 开发与发布
|
|
217
|
+
## 开发
|
|
387
218
|
|
|
388
219
|
```bash
|
|
389
220
|
npm install
|
|
390
|
-
npm run build
|
|
391
|
-
npm test
|
|
392
|
-
node test/interop.mjs # 改了签名相关代码后跑:输出 {pk, text, sign} 供后端验签
|
|
221
|
+
npm run build # dist/index.mjs + index.cjs + index.umd.js
|
|
222
|
+
npm test
|
|
393
223
|
```
|
|
394
224
|
|
|
395
|
-
发布:
|
|
396
|
-
|
|
397
|
-
```bash
|
|
398
|
-
npm version patch # 或 minor / major
|
|
399
|
-
npm run build && npm test
|
|
400
|
-
npm publish --registry=https://registry.npmjs.org/
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
- 安装走国内镜像没问题(`registry.npmmirror.com` 会自动同步);
|
|
404
|
-
- **发布/查询版本必须显式指定官方源** `--registry=https://registry.npmjs.org/`;
|
|
405
|
-
- 账号开了 2FA 时,token 需要勾 **Bypass 2FA**,否则 `npm publish` 会 403。
|
|
406
|
-
|
|
407
225
|
## License
|
|
408
226
|
|
|
409
227
|
MIT
|