@huaweidevtools/aishell-dsh-client-credentials 0.0.8 → 0.0.9

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.
@@ -20,26 +20,32 @@ export declare const zh: {
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.manual': "配置华为云凭据";
24
- readonly 'form.prefilledFromEnv': "检测到环境变量,已填入表单";
23
+ readonly 'form.title': "华为云 IAM 认证";
24
+ readonly 'form.or': "或者";
25
+ readonly 'form.signedIn': "已登录";
26
+ readonly 'form.logout': "退出";
27
+ readonly 'form.browser.section': "选项一:浏览器登录";
28
+ readonly 'form.browser.action': "登录";
29
+ readonly 'form.browser.checking': "环境检测中…";
30
+ readonly 'form.browser.unsupported': "当前环境不支持该方式。";
31
+ readonly 'form.browser.unsupportedLabel': "不支持";
32
+ readonly 'form.browser.cancelLabel': "取消登录";
33
+ readonly 'form.browser.running': "登录中({time})";
34
+ readonly 'form.browser.notOpened': "若浏览器未自动打开,请";
35
+ readonly 'form.browser.copyLink': "手动复制链接到浏览器打开";
36
+ readonly 'form.browser.blocked': "浏览器拦截了新标签页,请允许弹出窗口后重试。";
37
+ readonly 'form.browser.copyFailed': "无法复制链接,请手动从浏览器地址栏重试。";
38
+ readonly 'form.browser.failed': "浏览器登录未完成。";
39
+ readonly 'form.browser.startFailed': "无法启动浏览器登录,请改用 AK/SK 或稍后重试。";
40
+ readonly 'form.browser.expired': "登录超时,请重试。";
41
+ readonly 'form.manual.section': "选项二:配置 AK/SK";
42
+ readonly 'form.prefilledFromEnv': "已填入检测到的环境变量";
25
43
  readonly 'form.submit': "提交";
26
44
  readonly 'form.dismiss': "取消";
27
45
  readonly 'form.failed': "保存凭据失败";
28
- readonly 'form.clear': "清除";
29
46
  readonly 'form.clearing': "清除中…";
30
47
  readonly 'form.clear.failed': "清除凭据失败";
31
48
  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
49
  readonly 'section.field.accessKey': "Access Key";
44
50
  readonly 'section.field.accessKey.placeholder': "华为云 Access Key";
45
51
  readonly 'section.field.accessKey.hint': "Access Key 与 Secret Key 须同时填写,只填其一时不会保存。";
@@ -65,26 +71,32 @@ export declare const en: {
65
71
  readonly 'section.credentials.hint.link': "API Explorer";
66
72
  readonly 'section.credentials.hint.suffix': "and avoid permanent ones.";
67
73
  readonly 'section.credentials.saving': "Saving…";
68
- readonly 'form.title.manual': "Configure Huawei Cloud credentials";
69
- readonly 'form.prefilledFromEnv': "Detected environment variables — filled in from them";
74
+ readonly 'form.title': "Huawei Cloud IAM authentication";
75
+ readonly 'form.or': "or";
76
+ readonly 'form.signedIn': "Signed in";
77
+ readonly 'form.logout': "Logout";
78
+ readonly 'form.browser.section': "Option 1: sign in with a browser";
79
+ readonly 'form.browser.action': "Sign in";
80
+ readonly 'form.browser.checking': "Checking this environment…";
81
+ readonly 'form.browser.unsupported': "This environment does not support that method.";
82
+ readonly 'form.browser.unsupportedLabel': "Unsupported";
83
+ readonly 'form.browser.cancelLabel': "Cancel sign-in";
84
+ readonly 'form.browser.running': "Signing in ({time})";
85
+ readonly 'form.browser.notOpened': "If the browser did not open,";
86
+ readonly 'form.browser.copyLink': "copy the link into your browser";
87
+ readonly 'form.browser.blocked': "The browser blocked the new tab. Allow pop-ups for this page, then try again.";
88
+ readonly 'form.browser.copyFailed': "Could not copy the link. Try again from the browser address bar.";
89
+ readonly 'form.browser.failed': "The browser sign-in did not complete.";
90
+ readonly 'form.browser.startFailed': "Could not start the browser sign-in. Use an AK/SK instead, or try again.";
91
+ readonly 'form.browser.expired': "The sign-in timed out. Try again.";
92
+ readonly 'form.manual.section': "Option 2: configure an AK/SK";
93
+ readonly 'form.prefilledFromEnv': "Filled in from detected environment variables";
70
94
  readonly 'form.submit': "Submit";
71
95
  readonly 'form.dismiss': "Cancel";
72
96
  readonly 'form.failed': "Could not save credentials";
73
- readonly 'form.clear': "Clear";
74
97
  readonly 'form.clearing': "Clearing…";
75
98
  readonly 'form.clear.failed': "Could not clear credentials";
76
99
  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
100
  readonly 'section.field.accessKey': "Access Key";
89
101
  readonly 'section.field.accessKey.placeholder': "Huawei Access Key";
90
102
  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 this deployment do it at all?** Answered by the probe, on demand,
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
- * The cloud posts the credential to `127.0.0.1` *as the browser's machine
17
- * resolves it*, so the flow only works when the browser and the host are the
18
- * same machine. That is not knowable from either side: an SSH-forwarded
19
- * session makes a distant browser look local to the host, and a distant host
20
- * look local to the page. So the browser asks a question only it can ask —
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
- * `start` binds a loopback port on the host and fetches the provider's
31
- * callback plan. That work is not wasted when the answer is yes — it is the
32
- * login, already begun, and clicking the entry only opens the URL it returned.
33
- * When the answer is no, the port is released immediately.
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
- * Reachability check, then login.
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
- * Starts a login on the host and then proves this page can reach the listener
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
- * ## Why the probe is not a plain GET
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
- * It carries a custom header, which makes it a non-simple request: the browser
69
- * must send a CORS preflight first, and only proceeds if the answer is right.
70
- * The cloud's callback is a JSON POST and therefore *always* preflights, so a
71
- * plain GET would test a path the callback never takes — and could pass on a
72
- * deployment where the real preflight fails (a missing Private Network Access
73
- * allow header, say), which is the one wrong answer this check must not give.
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
- * @returns a handle when the login is reachable, or `undefined` when it is
76
- * not — the ordinary outcome on a deployment where the browser is elsewhere.
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 URL in a new tab.
102
+ * Open a blank tab now, and point it at the login page once there is one.
81
103
  *
82
- * A separate tab rather than a redirect: the form has unsaved state and the
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
- * ## Why `noopener` is set after opening, not passed in
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. Passing it there would make
90
- * every successful open look blocked, so the tab is opened plainly and the
91
- * opener reference is severed immediately afterwards, which is the same
92
- * protection without losing the success signal.
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
- * @param url - the URL the host returned.
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(url: string): boolean;
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 its preflight answer,
29
- * and a mismatch between the two is a probe that fails on a deployment that
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, where to probe
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
- * One browser login, start to finish.
3
- *
4
- * ## What this module does
5
- *
6
- * The whole out-of-band flow, in the order the constraints force:
7
- *
8
- * 1. Bind the loopback port. **First**, because the port is not a secret — a
9
- * local process could take it — and because the redirect URI cannot be
10
- * formed without the port the OS just assigned.
11
- * 2. Ask the login service where the browser should go, and what callback to
12
- * expect. That answer is the only thing that knows the provider's quirks.
13
- * 3. Check the plan's address against what actually bound. A plan naming a
14
- * different port would leave the person signing in while nothing here
15
- * could ever receive the result, and the symptom would be a bare timeout.
16
- * 4. Start serving the plan, and answer the reachability probe so a
17
- * deployment where the callback cannot arrive says so immediately instead
18
- * of after the person has been through a cloud login.
19
- * 5. Hand the browser URL back so the caller can open it.
20
- * 6. Wait for the payload, then map it through the provider's
21
- * `credential_schema`.
22
- * 7. **Verify before returning.** The payload's origin cannot be
23
- * authenticated — a local process can post to the port and forge the
24
- * `Origin` header — so the only defense is asking the cloud whether the
25
- * credential works. See the module note in `./listener.ts`.
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` is the contract of this module: it resolves with a credential
30
- * that has already been proven against the cloud, or it rejects. A caller
31
- * cannot get an unverified credential out of it, because the one failure mode
32
- * that matters — a forged credential sailing into the store — is the one this
33
- * exists to prevent, and a boolean flag is something a caller can forget to
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 they are established by the same call:
52
- * verification both proves the credential and names the account it belongs to,
53
- * so separating them would leave the caller to look the name up again — which
54
- * is the bug this pairing avoids.
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
- * Find the provider to sign in with, and the schema its credentials use.
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
- * Everything it returns is settled by the time it returns except `credential`,
133
- * which resolves when the person finishes signing in. The bind, the plan fetch
134
- * and the plan check all happen first, so a caller that gets a login back
135
- * knows there is a listener and somewhere to send the browser — a failure in
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, verifier, and the probe path.
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.