@huaweidevtools/aishell-dsh-client-credentials 0.0.8 → 0.0.10
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/lib/client.js +665 -648
- package/lib/index.js +196 -71
- package/lib/types/client/CredentialRequestForm.d.ts +53 -47
- package/lib/types/client/card-state.d.ts +58 -0
- package/lib/types/client/locales.d.ts +44 -30
- package/lib/types/client/login-flow.d.ts +78 -42
- package/lib/types/login-status.d.ts +3 -3
- package/lib/types/out-of-band/flow.d.ts +20 -1
- package/lib/types/out-of-band/listener.d.ts +77 -0
- package/lib/types/out-of-band/login.d.ts +67 -88
- package/lib/types/out-of-band/routes.d.ts +61 -33
- package/package.json +2 -2
- package/lib/types/client/spinner.d.ts +0 -32
- package/lib/types/client/start-page.d.ts +0 -61
|
@@ -16,30 +16,37 @@ export declare const zh: {
|
|
|
16
16
|
readonly 'mode.unavailable.hint': "无法读取权限模式;切换按钮暂不可用";
|
|
17
17
|
readonly 'mode.switchToReadonly': "切换为只读模式";
|
|
18
18
|
readonly 'mode.switchToReadwrite': "切换为读写模式";
|
|
19
|
-
readonly 'section.credentials.hint.prefix': "
|
|
19
|
+
readonly 'section.credentials.hint.prefix': "建议从";
|
|
20
20
|
readonly 'section.credentials.hint.link': "API Explorer";
|
|
21
21
|
readonly 'section.credentials.hint.suffix': "获取临时凭据,避免使用永久凭据。";
|
|
22
22
|
readonly 'section.credentials.saving': "保存中…";
|
|
23
|
-
readonly 'form.title
|
|
24
|
-
readonly 'form.
|
|
23
|
+
readonly 'form.title': "华为云 IAM 认证";
|
|
24
|
+
readonly 'form.or': "或者";
|
|
25
|
+
readonly 'form.signedIn': "已登录";
|
|
26
|
+
readonly 'form.confirm': "确认";
|
|
27
|
+
readonly 'form.logout': "退出";
|
|
28
|
+
readonly 'form.browser.section': "选项一:浏览器登录";
|
|
29
|
+
readonly 'form.browser.action': "登录";
|
|
30
|
+
readonly 'form.browser.checking': "环境检测中…";
|
|
31
|
+
readonly 'form.browser.unsupported': "当前环境不支持该方式。";
|
|
32
|
+
readonly 'form.browser.unsupportedLabel': "不支持";
|
|
33
|
+
readonly 'form.browser.cancelLabel': "取消登录";
|
|
34
|
+
readonly 'form.browser.running': "登录中({time})";
|
|
35
|
+
readonly 'form.browser.notOpened': "若浏览器未自动打开,请";
|
|
36
|
+
readonly 'form.browser.copyLink': "手动复制链接到浏览器打开";
|
|
37
|
+
readonly 'form.browser.blocked': "浏览器拦截了新标签页,请允许弹出窗口后重试。";
|
|
38
|
+
readonly 'form.browser.copyFailed': "无法复制链接,请手动从浏览器地址栏重试。";
|
|
39
|
+
readonly 'form.browser.failed': "浏览器登录未完成。";
|
|
40
|
+
readonly 'form.browser.startFailed': "无法启动浏览器登录,请改用 AK/SK 或稍后重试。";
|
|
41
|
+
readonly 'form.browser.expired': "登录超时,请重试。";
|
|
42
|
+
readonly 'form.manual.section': "选项二:配置 AK/SK";
|
|
43
|
+
readonly 'form.prefilledFromEnv': "已填入检测到的环境变量";
|
|
25
44
|
readonly 'form.submit': "提交";
|
|
26
45
|
readonly 'form.dismiss': "取消";
|
|
27
46
|
readonly 'form.failed': "保存凭据失败";
|
|
28
|
-
readonly 'form.clear': "清除";
|
|
29
47
|
readonly 'form.clearing': "清除中…";
|
|
30
48
|
readonly 'form.clear.failed': "清除凭据失败";
|
|
31
49
|
readonly 'error.unreachable': "无法连接宿主凭据服务:";
|
|
32
|
-
readonly 'form.intro': "需要进行华为云 IAM 认证";
|
|
33
|
-
readonly 'form.checking': "正在检查登录方式…";
|
|
34
|
-
readonly 'form.browser.action': "浏览器登录";
|
|
35
|
-
readonly 'form.browser.aksk': "我有AK/SK";
|
|
36
|
-
readonly 'form.browser.decline': "暂不认证";
|
|
37
|
-
readonly 'form.browser.waiting': "正在等待浏览器完成登录…";
|
|
38
|
-
readonly 'form.browser.countdown': "剩余 {time}";
|
|
39
|
-
readonly 'form.browser.reopen': "重新打开";
|
|
40
|
-
readonly 'form.back': "返回";
|
|
41
|
-
readonly 'form.browser.blocked': "浏览器拦截了新标签页,请允许弹出窗口后重试。";
|
|
42
|
-
readonly 'form.browser.failed': "浏览器登录未完成:";
|
|
43
50
|
readonly 'section.field.accessKey': "Access Key";
|
|
44
51
|
readonly 'section.field.accessKey.placeholder': "华为云 Access Key";
|
|
45
52
|
readonly 'section.field.accessKey.hint': "Access Key 与 Secret Key 须同时填写,只填其一时不会保存。";
|
|
@@ -61,30 +68,37 @@ export declare const en: {
|
|
|
61
68
|
readonly 'mode.unavailable.hint': "Could not read the permission mode; the toggle is unavailable";
|
|
62
69
|
readonly 'mode.switchToReadonly': "Switch to read-only mode";
|
|
63
70
|
readonly 'mode.switchToReadwrite': "Switch to read-write mode";
|
|
64
|
-
readonly 'section.credentials.hint.prefix': "
|
|
71
|
+
readonly 'section.credentials.hint.prefix': "Obtain temporary credentials from";
|
|
65
72
|
readonly 'section.credentials.hint.link': "API Explorer";
|
|
66
73
|
readonly 'section.credentials.hint.suffix': "and avoid permanent ones.";
|
|
67
74
|
readonly 'section.credentials.saving': "Saving…";
|
|
68
|
-
readonly 'form.title
|
|
69
|
-
readonly 'form.
|
|
75
|
+
readonly 'form.title': "Huawei Cloud IAM authentication";
|
|
76
|
+
readonly 'form.or': "or";
|
|
77
|
+
readonly 'form.signedIn': "Signed in";
|
|
78
|
+
readonly 'form.confirm': "Confirm";
|
|
79
|
+
readonly 'form.logout': "Logout";
|
|
80
|
+
readonly 'form.browser.section': "Option 1: sign in with a browser";
|
|
81
|
+
readonly 'form.browser.action': "Sign in";
|
|
82
|
+
readonly 'form.browser.checking': "Checking this environment…";
|
|
83
|
+
readonly 'form.browser.unsupported': "This environment does not support this method.";
|
|
84
|
+
readonly 'form.browser.unsupportedLabel': "Unsupported";
|
|
85
|
+
readonly 'form.browser.cancelLabel': "Cancel sign-in";
|
|
86
|
+
readonly 'form.browser.running': "Signing in ({time})";
|
|
87
|
+
readonly 'form.browser.notOpened': "If the browser did not open,";
|
|
88
|
+
readonly 'form.browser.copyLink': "copy the link into your browser";
|
|
89
|
+
readonly 'form.browser.blocked': "The browser blocked the new tab. Allow pop-ups for this page, then try again.";
|
|
90
|
+
readonly 'form.browser.copyFailed': "Could not copy the link. Try again from the browser address bar.";
|
|
91
|
+
readonly 'form.browser.failed': "The browser sign-in did not complete.";
|
|
92
|
+
readonly 'form.browser.startFailed': "Could not start the browser sign-in. Use an AK/SK instead, or try again.";
|
|
93
|
+
readonly 'form.browser.expired': "The sign-in timed out. Try again.";
|
|
94
|
+
readonly 'form.manual.section': "Option 2: configure an AK/SK";
|
|
95
|
+
readonly 'form.prefilledFromEnv': "Filled in from detected environment variables";
|
|
70
96
|
readonly 'form.submit': "Submit";
|
|
71
97
|
readonly 'form.dismiss': "Cancel";
|
|
72
98
|
readonly 'form.failed': "Could not save credentials";
|
|
73
|
-
readonly 'form.clear': "Clear";
|
|
74
99
|
readonly 'form.clearing': "Clearing…";
|
|
75
100
|
readonly 'form.clear.failed': "Could not clear credentials";
|
|
76
101
|
readonly 'error.unreachable': "Could not reach the host credential service: ";
|
|
77
|
-
readonly 'form.intro': "Huawei Cloud IAM authentication is required";
|
|
78
|
-
readonly 'form.checking': "Checking sign-in options…";
|
|
79
|
-
readonly 'form.browser.action': "Sign in with a browser";
|
|
80
|
-
readonly 'form.browser.aksk': "I have one";
|
|
81
|
-
readonly 'form.browser.decline': "Not now";
|
|
82
|
-
readonly 'form.browser.waiting': "Waiting for the browser sign-in to finish…";
|
|
83
|
-
readonly 'form.browser.countdown': "{time} left";
|
|
84
|
-
readonly 'form.browser.reopen': "Reopen";
|
|
85
|
-
readonly 'form.back': "Back";
|
|
86
|
-
readonly 'form.browser.blocked': "The browser blocked the new tab. Allow pop-ups for this page, then try again.";
|
|
87
|
-
readonly 'form.browser.failed': "The browser sign-in did not complete: ";
|
|
88
102
|
readonly 'section.field.accessKey': "Access Key";
|
|
89
103
|
readonly 'section.field.accessKey.placeholder': "Huawei Access Key";
|
|
90
104
|
readonly 'section.field.accessKey.hint': "Access Key and Secret Key are stored as a pair; one without the other is not saved.";
|
|
@@ -5,32 +5,26 @@
|
|
|
5
5
|
*
|
|
6
6
|
* Two things, and they arrive by different routes:
|
|
7
7
|
*
|
|
8
|
-
* - **Can
|
|
9
|
-
* because only the browser can answer it. See below.
|
|
8
|
+
* - **Can the browser reach the host from where it is?** Answered by the
|
|
9
|
+
* probe, on demand, because only the browser can answer it. See below.
|
|
10
10
|
* - **How did the last attempt end?** Read from the entry's settings
|
|
11
11
|
* document, which the host writes when the credential lands — the person
|
|
12
12
|
* may be at the cloud for minutes, so there is nothing to await.
|
|
13
13
|
*
|
|
14
14
|
* ## Why the capability is probed rather than assumed
|
|
15
15
|
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
* *can I reach the host's listener?* — by fetching it.
|
|
22
|
-
*
|
|
23
|
-
* This is also why the capability is never cached. Reachability depends on
|
|
24
|
-
* things that change under the user's feet (a VPN, a tunnel, a port taken
|
|
25
|
-
* between attempts), and a cached "no" would keep the entry hidden after
|
|
26
|
-
* someone fixed their setup.
|
|
16
|
+
* A browser login works only when the browser can reach a listener on the
|
|
17
|
+
* host. Neither side can tell by looking: an SSH-forwarded session makes a
|
|
18
|
+
* distant browser look local to the host, and a distant host look local to the
|
|
19
|
+
* page. So the browser asks a question only it can ask — *can I reach the
|
|
20
|
+
* host's listener?* — by fetching it. See {@link probeBrowserRoute}.
|
|
27
21
|
*
|
|
28
22
|
* ## The cost of asking
|
|
29
23
|
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
24
|
+
* The probe borrows a loopback port on the host, is answered once, and gives
|
|
25
|
+
* the port back. It does not begin a login: a card read and abandoned holds
|
|
26
|
+
* nothing. Clicking the button is what binds a port for real, through
|
|
27
|
+
* {@link startBrowserLogin}.
|
|
34
28
|
*
|
|
35
29
|
* @module @huaweidevtools/aishell-dsh-client-credentials/client/login-flow
|
|
36
30
|
*/
|
|
@@ -57,42 +51,84 @@ export interface BrowserLoginHandle {
|
|
|
57
51
|
readonly cancel: () => void;
|
|
58
52
|
}
|
|
59
53
|
/**
|
|
60
|
-
*
|
|
54
|
+
* Ask whether a browser here can reach a loopback listener.
|
|
55
|
+
*
|
|
56
|
+
* ## What it tests, and why only this can
|
|
57
|
+
*
|
|
58
|
+
* The cloud posts a credential to `127.0.0.1` **as the browser's machine
|
|
59
|
+
* resolves it**, so the flow works only when that browser can reach a listener
|
|
60
|
+
* on this host. Neither side can tell by looking: an SSH-forwarded session
|
|
61
|
+
* makes a distant browser look local to the host, and a distant host look local
|
|
62
|
+
* to the page. So the host borrows a port, this page fetches it, and the fetch
|
|
63
|
+
* *is* the answer — resolving means a socket here was reached, rejecting means
|
|
64
|
+
* it was not.
|
|
65
|
+
*
|
|
66
|
+
* The port is released by the host as soon as it is reached, or after a short
|
|
67
|
+
* window. Nothing is kept for the login that may follow: that binds its own
|
|
68
|
+
* port, so a card read and abandoned holds nothing.
|
|
61
69
|
*
|
|
62
|
-
*
|
|
63
|
-
* it bound. The probe request goes from this browser to loopback, which is the
|
|
64
|
-
* same journey the cloud's callback will make.
|
|
70
|
+
* ## Why the request carries a header
|
|
65
71
|
*
|
|
66
|
-
*
|
|
72
|
+
* The header makes it a non-simple request, so the browser sends a CORS
|
|
73
|
+
* preflight first and only proceeds if the answer is right. The cloud's
|
|
74
|
+
* callback is a JSON POST and therefore *always* preflights, so a plain GET
|
|
75
|
+
* would test a path the callback never takes — and could pass on a route where
|
|
76
|
+
* the real preflight fails, which is the one wrong answer this must not
|
|
77
|
+
* give.
|
|
67
78
|
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
*
|
|
79
|
+
* @returns whether the route works here. Answered once per page, except when
|
|
80
|
+
* the host could not be reached — see {@link routeProbe}.
|
|
81
|
+
*/
|
|
82
|
+
export declare function probeBrowserRoute(signal?: AbortSignal): Promise<boolean>;
|
|
83
|
+
/**
|
|
84
|
+
* Drop the remembered probe answer.
|
|
74
85
|
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
86
|
+
* For tests, which need each case to probe for itself. Not called in
|
|
87
|
+
* production: the answer is deliberately kept for the life of the page, and
|
|
88
|
+
* discarding it would only make the next card ask again.
|
|
89
|
+
*/
|
|
90
|
+
export declare function __resetRouteProbe(): void;
|
|
91
|
+
/**
|
|
92
|
+
* Begin a login, now that the person has asked for one.
|
|
93
|
+
*
|
|
94
|
+
* Binds a port and fetches a URL projected for it at this moment, which is why
|
|
95
|
+
* the URL is not stale however long the card sat open before the click.
|
|
96
|
+
*
|
|
97
|
+
* @returns a handle for the login in flight, or `undefined` when the host
|
|
98
|
+
* could not start one.
|
|
77
99
|
*/
|
|
78
100
|
export declare function startBrowserLogin(): Promise<BrowserLoginHandle | undefined>;
|
|
79
101
|
/**
|
|
80
|
-
* Open a login
|
|
102
|
+
* Open a blank tab now, and point it at the login page once there is one.
|
|
81
103
|
*
|
|
82
|
-
*
|
|
83
|
-
* person may come back to paste a key instead, and a login that navigated away
|
|
84
|
-
* from the conversation would lose it.
|
|
104
|
+
* ## Why the window is opened before the URL exists
|
|
85
105
|
*
|
|
86
|
-
*
|
|
106
|
+
* A popup is only allowed while the user gesture is live, and a gesture does
|
|
107
|
+
* not survive an `await`. Fetching the login URL first — which is what this
|
|
108
|
+
* has to do, because the URL names a port the host has not bound yet — would
|
|
109
|
+
* spend the gesture, and a blocker would then refuse the tab. Opening the tab
|
|
110
|
+
* synchronously and navigating it a moment later keeps the gesture intact.
|
|
111
|
+
*
|
|
112
|
+
* ## Why the opener reference is severed afterwards
|
|
87
113
|
*
|
|
88
114
|
* `window.open` returns `null` whenever `noopener` appears in its features
|
|
89
|
-
* string — by specification, not as a failure
|
|
90
|
-
* every successful open look blocked
|
|
91
|
-
*
|
|
92
|
-
*
|
|
115
|
+
* string — by specification, not as a failure — so passing it there would make
|
|
116
|
+
* every successful open look blocked. The reference is cut immediately after
|
|
117
|
+
* instead, which is the same protection without losing the success signal.
|
|
118
|
+
*
|
|
119
|
+
* @returns a handle whose `navigate` shows the login page, or `undefined` when
|
|
120
|
+
* the browser refused to open a tab at all.
|
|
121
|
+
*/
|
|
122
|
+
export interface LoginWindow {
|
|
123
|
+
/** Point the tab at the login page. */
|
|
124
|
+
readonly navigate: (url: string) => void;
|
|
125
|
+
/** Close the blank tab, when the login could not be started. */
|
|
126
|
+
readonly close: () => void;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Open a blank tab, subject to the current user gesture.
|
|
93
130
|
*
|
|
94
|
-
* @
|
|
95
|
-
* @returns whether the browser opened it; a popup blocker says no.
|
|
131
|
+
* @returns the handle, or `undefined` when a blocker refused.
|
|
96
132
|
*/
|
|
97
|
-
export declare function openLoginWindow(
|
|
133
|
+
export declare function openLoginWindow(): LoginWindow | undefined;
|
|
98
134
|
//# sourceMappingURL=login-flow.d.ts.map
|
|
@@ -25,9 +25,9 @@ export declare const LOGIN_OUTCOME_FIELD = "loginOutcome";
|
|
|
25
25
|
*
|
|
26
26
|
* Any non-safelisted header would do it; this one names why. Declared here
|
|
27
27
|
* because both halves need the same string and neither owns it: the browser
|
|
28
|
-
* half sends it, the host's listener must allow it in
|
|
29
|
-
* and a mismatch between the two is a probe that fails
|
|
30
|
-
* would actually work — the entry hidden for no reason.
|
|
28
|
+
* half sends it on the loopback fetch, the host's listener must allow it in
|
|
29
|
+
* its preflight answer, and a mismatch between the two is a probe that fails
|
|
30
|
+
* on a route that would actually work — the entry hidden for no reason.
|
|
31
31
|
*/
|
|
32
32
|
export declare const PROBE_HEADER = "x-aishell-probe";
|
|
33
33
|
/** How a browser login ended. */
|
|
@@ -3,8 +3,11 @@
|
|
|
3
3
|
*
|
|
4
4
|
* ## The shape of a login
|
|
5
5
|
*
|
|
6
|
+
* probe() borrow a port, let the page fetch it, give it back
|
|
7
|
+
* | -> whether a browser here can reach this host at all
|
|
8
|
+
* v
|
|
6
9
|
* begin(provider) bind a port, fetch the plan, start serving
|
|
7
|
-
* | -> where to send the browser
|
|
10
|
+
* | -> where to send the browser
|
|
8
11
|
* v
|
|
9
12
|
* (the person signs in at the cloud, in their browser, for up to 10 minutes)
|
|
10
13
|
* v
|
|
@@ -12,6 +15,11 @@
|
|
|
12
15
|
* v
|
|
13
16
|
* verify against IAM -> store -> record the outcome for the browser half
|
|
14
17
|
*
|
|
18
|
+
* Probe and login are separate operations on purpose — see `./login.ts` for
|
|
19
|
+
* why. The probe answers a question about the access route and holds a port
|
|
20
|
+
* for seconds; the login binds its own and holds it for as long as the person
|
|
21
|
+
* takes.
|
|
22
|
+
*
|
|
15
23
|
* The outcome does not come back as a return value, because there is nothing
|
|
16
24
|
* waiting on it: the person may take minutes, and an HTTP request held open
|
|
17
25
|
* that long is a request a proxy will cut. So the outcome is *recorded* — in
|
|
@@ -66,6 +74,17 @@ export interface LoginFlowDeps {
|
|
|
66
74
|
export interface LoginFlow {
|
|
67
75
|
/** Look up a provider; `undefined` when the service does not offer it. */
|
|
68
76
|
readonly findProvider: (providerId: string) => Promise<ProviderInfo | undefined>;
|
|
77
|
+
/**
|
|
78
|
+
* Borrow a loopback port and hand back a URL the page can fetch.
|
|
79
|
+
*
|
|
80
|
+
* Reaching it is the whole test, and the page is the one that learns the
|
|
81
|
+
* answer — see `./listener.ts`. The port is released as soon as it is
|
|
82
|
+
* reached, or after a short window if the page never gets there, so a card
|
|
83
|
+
* left open holds nothing.
|
|
84
|
+
*/
|
|
85
|
+
readonly probe: () => Promise<{
|
|
86
|
+
probeUrl: string;
|
|
87
|
+
}>;
|
|
69
88
|
/** Begin a login. Rejects when one is already running. */
|
|
70
89
|
readonly begin: (provider: ProviderInfo) => Promise<LoginStartResult>;
|
|
71
90
|
/** Abandon the login in progress, if any. Safe to call with none. */
|
|
@@ -99,6 +99,76 @@ export interface BoundListener {
|
|
|
99
99
|
/** Stop listening without ever having served. */
|
|
100
100
|
readonly close: () => void;
|
|
101
101
|
}
|
|
102
|
+
/**
|
|
103
|
+
* Borrow a loopback port, answer one probe, and give it back.
|
|
104
|
+
*
|
|
105
|
+
* ## What this is for
|
|
106
|
+
*
|
|
107
|
+
* The cloud posts a credential to `127.0.0.1` **as the browser's machine
|
|
108
|
+
* resolves it**, so a browser login works only when that browser can reach a
|
|
109
|
+
* listener on this host. Neither side can tell by looking — an SSH-forwarded
|
|
110
|
+
* session makes a distant browser look local to the host and a distant host
|
|
111
|
+
* look local to the page — so the page fetches a URL and the fetch is the
|
|
112
|
+
* answer. A fetch that resolves means the page reached a socket here.
|
|
113
|
+
*
|
|
114
|
+
* ## How it ends
|
|
115
|
+
*
|
|
116
|
+
* Two ways, whichever comes first:
|
|
117
|
+
*
|
|
118
|
+
* - **Someone reaches it.** The response is written, and the socket closes
|
|
119
|
+
* immediately after — the question has been answered, so the port has no
|
|
120
|
+
* further use.
|
|
121
|
+
* - **{@link PROBE_WINDOW_MS} passes.** Nobody came, which is itself an
|
|
122
|
+
* answer (this browser cannot reach loopback), and the socket closes.
|
|
123
|
+
*
|
|
124
|
+
* Either way the port is held for seconds at most. A probe borrowed to ask one
|
|
125
|
+
* question must not outlive the asking — a card left open would otherwise keep
|
|
126
|
+
* a socket for the life of the page, which is what the earlier design did.
|
|
127
|
+
*
|
|
128
|
+
* ## Why the nonce
|
|
129
|
+
*
|
|
130
|
+
* The probe answers whatever origin asks, because the page's own origin is by
|
|
131
|
+
* definition not one of the cloud's. That is only safe with a secret: without
|
|
132
|
+
* one, any page that swept local ports would get an answer, making this a
|
|
133
|
+
* fingerprinting beacon for the plugin's presence. A caller without the nonce
|
|
134
|
+
* is answered exactly as an empty port would be.
|
|
135
|
+
*
|
|
136
|
+
* ## What the caller gets, and what it does not
|
|
137
|
+
*
|
|
138
|
+
* A URL and nothing else. The caller cannot observe the port closing — it
|
|
139
|
+
* closes on its own, either on being reached or when the window runs out — and
|
|
140
|
+
* a promise for that would be a handle no caller has a use for. Awaiting it
|
|
141
|
+
* would also mean a route waiting up to the whole window before answering,
|
|
142
|
+
* which is precisely what the page cannot afford.
|
|
143
|
+
*
|
|
144
|
+
* @param path - the path the probe is served on.
|
|
145
|
+
* @returns the URL to hand the page.
|
|
146
|
+
*/
|
|
147
|
+
export declare function probeLoopback(path: string): Promise<{
|
|
148
|
+
readonly probeUrl: string;
|
|
149
|
+
}>;
|
|
150
|
+
/**
|
|
151
|
+
* Detach a timer from the event loop, when the runtime has that notion.
|
|
152
|
+
*
|
|
153
|
+
* Node's timer objects carry `unref`; a browser's are numbers. This package's
|
|
154
|
+
* tsconfig compiles against the DOM signature (the browser half is most of
|
|
155
|
+
* it), so the method is reached through a narrow cast rather than declared.
|
|
156
|
+
*
|
|
157
|
+
* Exported because the login's deadline needs the same treatment, and two
|
|
158
|
+
* copies of a three-line cast is how they drift.
|
|
159
|
+
*
|
|
160
|
+
* @param timer - the timer handle, of whichever shape this runtime uses.
|
|
161
|
+
*/
|
|
162
|
+
export declare function unrefIfPossible(timer: ReturnType<typeof setTimeout> | undefined): void;
|
|
163
|
+
/**
|
|
164
|
+
* How long a probe port is held.
|
|
165
|
+
*
|
|
166
|
+
* Generous for a request that takes under a millisecond when it works, because
|
|
167
|
+
* the cost of the wait is a bound port and the cost of being too quick is
|
|
168
|
+
* calling a working route unsupported. A page that is slow to get going —
|
|
169
|
+
* a large bundle still parsing — still gets its answer.
|
|
170
|
+
*/
|
|
171
|
+
export declare const PROBE_WINDOW_MS = 30000;
|
|
102
172
|
/** How the probe asks for a pass. */
|
|
103
173
|
export interface ProbeConfig {
|
|
104
174
|
/**
|
|
@@ -121,6 +191,13 @@ export interface ProbeConfig {
|
|
|
121
191
|
* an answer.
|
|
122
192
|
*/
|
|
123
193
|
readonly nonce: string;
|
|
194
|
+
/**
|
|
195
|
+
* Called when the probe has been answered, so the socket can be given back.
|
|
196
|
+
*
|
|
197
|
+
* Fired after the response is written, which is what makes the answer true:
|
|
198
|
+
* the page's fetch resolved, so it reached a socket here.
|
|
199
|
+
*/
|
|
200
|
+
readonly onAnswered?: () => void;
|
|
124
201
|
}
|
|
125
202
|
/** A listener honouring a plan, and the one credential it will accept. */
|
|
126
203
|
export interface CallbackListener {
|
|
@@ -1,37 +1,42 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
* ##
|
|
5
|
-
*
|
|
6
|
-
* The
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
2
|
+
* The browser-login flow, as two separate operations.
|
|
3
|
+
*
|
|
4
|
+
* ## Why two, and not one
|
|
5
|
+
*
|
|
6
|
+
* The card has to answer "can the browser reach a listener here?" before
|
|
7
|
+
* offering the button, and answering it requires binding a loopback socket —
|
|
8
|
+
* the question is whether the browser can reach a listener here, and nothing
|
|
9
|
+
* weaker answers it. That lives in `./listener.ts` as `probeLoopback`.
|
|
10
|
+
*
|
|
11
|
+
* A login is a different thing: fetch a URL for a specific port, send the
|
|
12
|
+
* person there, wait for the cloud to post a credential back. That is
|
|
13
|
+
* {@link startBrowserLogin}, and it binds **its own** port.
|
|
14
|
+
*
|
|
15
|
+
* These were one function, and it was wrong in two ways that only show up when
|
|
16
|
+
* a person takes their time:
|
|
17
|
+
*
|
|
18
|
+
* - **The port was held from the moment the card opened.** The probe binds a
|
|
19
|
+
* socket to answer its question and now releases it immediately; keeping it
|
|
20
|
+
* until someone clicked meant anyone who read the card and walked away held
|
|
21
|
+
* a port for as long as the page lived.
|
|
22
|
+
* - **The login window started before the person did.** The `login_url` names
|
|
23
|
+
* the port it was projected for and the service states how long it stays
|
|
24
|
+
* valid. Both were fixed at probe time, so a card left open for a while
|
|
25
|
+
* offered a URL that had already expired — and a countdown ran down on a
|
|
26
|
+
* sign-in nobody had begun.
|
|
27
|
+
*
|
|
28
|
+
* So each operation binds what it needs and releases it when its own job ends.
|
|
29
|
+
* The probe's port is closed as soon as the browser has answered; the login's
|
|
30
|
+
* port lives exactly as long as the login does, and the URL is fetched at the
|
|
31
|
+
* moment it is about to be opened.
|
|
26
32
|
*
|
|
27
33
|
* ## Why verification is not optional
|
|
28
34
|
*
|
|
29
|
-
* `credential`
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
* check.
|
|
35
|
+
* `credential` resolves with a credential already proven against the cloud, or
|
|
36
|
+
* it rejects. A caller cannot get an unverified credential out of it, because
|
|
37
|
+
* the one failure mode that matters — a forged credential reaching the store —
|
|
38
|
+
* is the one this exists to prevent, and a boolean flag is something a caller
|
|
39
|
+
* can forget to check.
|
|
35
40
|
*
|
|
36
41
|
* ## What verification does not catch
|
|
37
42
|
*
|
|
@@ -48,66 +53,38 @@ import { type ContractDeps, type MappedCredential, type ProviderInfo } from './c
|
|
|
48
53
|
* A credential that has been proven against the cloud, and whose account is
|
|
49
54
|
* therefore known.
|
|
50
55
|
*
|
|
51
|
-
* The two travel together because
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
56
|
+
* The two travel together because the same call establishes both: verification
|
|
57
|
+
* proves the credential and names the account it belongs to. Separating them
|
|
58
|
+
* would leave the caller to look the name up again, reading the store before
|
|
59
|
+
* the reconcile loop has caught up with the write.
|
|
55
60
|
*/
|
|
56
61
|
export interface VerifiedCredential {
|
|
57
62
|
readonly credential: MappedCredential;
|
|
58
63
|
/** The account the credential belongs to, as IAM reported it. */
|
|
59
64
|
readonly accountName: string;
|
|
60
65
|
}
|
|
61
|
-
/**
|
|
62
|
-
* A run of the browser-login flow.
|
|
63
|
-
*
|
|
64
|
-
* The two promises are separate rather than one: `loginUrl` resolves as soon
|
|
65
|
-
* as there is somewhere to send the browser, and `credential` resolves much
|
|
66
|
-
* later, when the person has finished. A single promise would make the caller
|
|
67
|
-
* wait for a URL it needs in order to start the wait.
|
|
68
|
-
*/
|
|
66
|
+
/** A login in flight. */
|
|
69
67
|
export interface BrowserLogin {
|
|
70
68
|
/** The address the callback listener bound to, `host:port`. */
|
|
71
69
|
readonly address: string;
|
|
72
|
-
/**
|
|
73
|
-
* URL to fetch from the page to test whether it can reach the listener.
|
|
74
|
-
*
|
|
75
|
-
* Known as soon as the login starts — the port and nonce are both fixed by
|
|
76
|
-
* then — so it is a plain value rather than a promise.
|
|
77
|
-
*/
|
|
78
|
-
readonly probeUrl: string;
|
|
79
70
|
/** Where to send the browser. */
|
|
80
71
|
readonly loginUrl: string;
|
|
81
|
-
/**
|
|
82
|
-
* How long the login stays valid, in seconds — the service's own figure.
|
|
83
|
-
*
|
|
84
|
-
* Sent to the browser half so the waiting card can count down to the moment
|
|
85
|
-
* the callback stops being possible, rather than showing an open-ended
|
|
86
|
-
* spinner.
|
|
87
|
-
*/
|
|
88
|
-
readonly expiresInSeconds: number;
|
|
89
|
-
/** The verified credential, or a rejection explaining why there is none. */
|
|
72
|
+
/** The credential, once the person has finished and the cloud accepted it. */
|
|
90
73
|
readonly credential: Promise<VerifiedCredential>;
|
|
74
|
+
/** How long the login stays valid, in seconds — the service's own figure. */
|
|
75
|
+
readonly expiresInSeconds: number;
|
|
91
76
|
/** Abandon the login: close the listener and reject anything pending. */
|
|
92
77
|
readonly cancel: () => void;
|
|
93
78
|
}
|
|
94
|
-
/**
|
|
95
|
-
|
|
96
|
-
*
|
|
97
|
-
* Separate from {@link startBrowserLogin} because it needs no socket: the
|
|
98
|
-
* browser half can ask "is this even available, and what am I signing in to?"
|
|
99
|
-
* before anything binds.
|
|
100
|
-
*
|
|
101
|
-
* @param providerId - the provider to look for.
|
|
102
|
-
* @param deps - transport overrides.
|
|
103
|
-
* @returns the provider, or `undefined` when the service does not offer it.
|
|
104
|
-
* @throws {AuthContractError} when the service is unreachable or answers unusably.
|
|
105
|
-
*/
|
|
106
|
-
export declare function findProvider(providerId: string, deps?: ContractDeps): Promise<ProviderInfo | undefined>;
|
|
107
|
-
/** Options for {@link startBrowserLogin}. */
|
|
108
|
-
export interface StartLoginOptions {
|
|
79
|
+
/** Transport and provider facts both operations need. */
|
|
80
|
+
export interface LoginContext {
|
|
109
81
|
/** The provider, as the service describes it — including its `credential_schema`. */
|
|
110
82
|
readonly provider: ProviderInfo;
|
|
83
|
+
/** Transport overrides for the contract calls. */
|
|
84
|
+
readonly contract?: ContractDeps | undefined;
|
|
85
|
+
}
|
|
86
|
+
/** Options for {@link startBrowserLogin}. */
|
|
87
|
+
export interface StartLoginOptions extends LoginContext {
|
|
111
88
|
/**
|
|
112
89
|
* Proves a credential works, and names the account it belongs to.
|
|
113
90
|
*
|
|
@@ -116,26 +93,28 @@ export interface StartLoginOptions {
|
|
|
116
93
|
* forget to check. The resolved name is what a successful login reports.
|
|
117
94
|
*/
|
|
118
95
|
readonly verify: (credential: MappedCredential) => Promise<unknown>;
|
|
119
|
-
/**
|
|
120
|
-
* Path the reachability probe is answered on.
|
|
121
|
-
*
|
|
122
|
-
* Supplied by the caller because the browser half must be told the same
|
|
123
|
-
* value, and it is the browser half that sends the probe.
|
|
124
|
-
*/
|
|
125
|
-
readonly probePath: string;
|
|
126
|
-
/** Transport overrides for the contract calls. */
|
|
127
|
-
readonly contract?: ContractDeps | undefined;
|
|
128
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Find the provider to sign in with, and the schema its credentials use.
|
|
99
|
+
*
|
|
100
|
+
* Needs no socket, so the card can ask "is this even on offer, and what am I
|
|
101
|
+
* signing in to?" before anything binds.
|
|
102
|
+
*
|
|
103
|
+
* @param providerId - the provider to look for.
|
|
104
|
+
* @param deps - transport overrides.
|
|
105
|
+
* @returns the provider, or `undefined` when the service does not offer it.
|
|
106
|
+
* @throws {AuthContractError} when the service is unreachable or answers unusably.
|
|
107
|
+
*/
|
|
108
|
+
export declare function findProvider(providerId: string, deps?: ContractDeps): Promise<ProviderInfo | undefined>;
|
|
129
109
|
/**
|
|
130
110
|
* Begin a browser login.
|
|
131
111
|
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
136
|
-
* any of those throws instead.
|
|
112
|
+
* Binds its own listener and fetches a login URL projected for it, so both are
|
|
113
|
+
* as fresh as the moment the person clicked — see the module note for why that
|
|
114
|
+
* matters. Everything except `credential` is settled by the time this returns;
|
|
115
|
+
* a failure to bind, reach the service, or match the plan throws instead.
|
|
137
116
|
*
|
|
138
|
-
* @param options - provider
|
|
117
|
+
* @param options - the provider and the verifier.
|
|
139
118
|
* @returns the running login.
|
|
140
119
|
* @throws {AuthContractError} when the port cannot be bound, the service
|
|
141
120
|
* cannot be reached, or the plan names an address this machine is not on.
|